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Preface 



This manual is a general reference for a standard CP/M system. 
Features of Apple SoftCard III CP/M may differ slightly in features 
or operation from the system described in this manual. Consult 
your SoftCard III Installation and Operation Manual for specific 
details. 



viii CP/M Reference Manual 



Introduction 1 



Introduction 

to CP/M Features and Facilities 



1 



2 


Introduction 


4 


Overview of CP/M 2.0 Facilities 


6 


Functional Description of CP/M 


7 


General Command Structure 


7 


File References 


10 


Switching Disks 


10 


Form of Built-in Commands 


11 


ERAse Command 


12 


Dl Rectory Command 


13 


REName Command 


14 


SAVE Command 


14 


TYPE Command 


15 


USER Command 


15 


Line Editing and Output Control 


17 


Transient Commands 


18 


STAT 


25 


ASM 


26 


LOAD 


27 


PIP 


37 


ED 


40 


SUBMIT 


42 


XSUB 


43 


DUMP 


43 


BDOS Error Messages 



2 CP/M Reference Manual 



1 

Introduction to 

CP/M Features and Facilities 



Introduction 



CP/M is a monitor control program for microcomputer system 
development which uses IBM-compatible flexible disks for backup 
storage. Using a computer mainframe based upon Intel's 8080 
microcomputer, CP/M provides a general environment for program 
construction, storage, and editing, along with assembly and program 
check-out facilities. An important feature of CP/M is that it can be 
easily altered to execute with any computer configuration which 
uses an Intel 8080 (or Zilog Z-80) Central Processing Unit, and has 
at least 16K bytes of main memory with up to four IBM-compatible 
diskette drives. Although the standard Digital Research version 
operates on a single-density Intel MDS 800, several different 
hardware manufacturers support their own input-output drivers for 
CP/M. 

The CP/M monitor provides rapid access to programs through a 
comprehensive file management package. The file subsystem 
supports a named file structure, allowing dynamic allocation of file 
space as well as sequential and random file access. Using this file 
system, a large number of distinct programs can be stored in both 
source and machine executable form. 

CP/M also supports a powerful context editor, Intel-compatible 
assembler, and debugger subsystem. Optional software includes a 
powerful Intel-compatible macro assembler, symbolic debugger, 
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along with various high-level languages. When coupled with CP/M's 
Console Command Processor, the resulting facilities equal or excel 
similar large computer facilities. 

CP/M is logically divided into several distinct parts: 



BIOS Basic I/O System (hardware dependent) 

BDOS Basic Disk Operating System 

CCP Console Command Processor 

TPA Transient Program Area 



The BIOS provides the primitive operations necessary to access 
the diskette drives and to interface standard peripherals (teletype, 
CRT, Paper Tape Reader/Punch, and user-defined peripherals), and 
can be tailored by the user for any particular hardware environment 
by "patching" this portion of CP/M. 

The BDOS provides disk management by controlling one or more 
disk drives containing independent file directories. The BDOS 
implements disk allocation strategies which provide fully dynamic 
file construction while minimizing head movement across the disk 
during access. Any particular file may contain any number of 
records, not exceeding the size of any single disk. In a standard 
CP/M system, each disk can contain up to 64 distinct files. The 
BDOS has entry points which include the following primitive 
operations which can be programmatically accessed: 



SEARCH 


Look for a particular disk file by name 


OPEN 


Open a file for further operations. 


CLOSE 


Close a file after processing. 


RENAME 


Change the name of a particular file. 


READ 


Read a record from a particular file. 


WRITE 


Write a record onto the disk. 


SELECT 


Select a particular disk drive for 




further operations. 
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The CCP provides symbolic interface between the user's console 
and the remainder of the CP/M system. The CCP reads the console 
device and processes commands which include listing the file 
directory, printing the contents of files, and controlling the operation 
of transient programs, such as assemblers, editors, and debuggers. 
The standard commands which are available in the CCP are listed 
in a following section. 

The last segment of CP/M is the area called the Transient Program 
Area (TPA). The TPA holds programs which are loaded from the 
disk under command of the CCP. During program editing, for 
example, the TPA holds the CP/M text editor machine code and 
data areas. Similarly, programs created under CP/M can be checked 
out by loading and executing these programs in the TPA. 

It should be mentioned that any or all of the CP/M component 
subsystems can be "overlayed" by an executing program. That is, 
once a user's program is loaded into the TPA, the CCP, BDOS, and 
BIOS areas can be used as the program's data area. A "bootstrap" 
loader is programmatically accessible whenever the BIOS portion 
is not overlayed; thus, the user program need only branch to the 
bootstrap loader at the end of execution, and the complete CP/M 
monitor is reloaded from disk. 

It should be reiterated that the CP/M operating system is partitioned 
into distinct modules, including the BIOS portion which defines the 
hardware environment in which CP/M is executing. Thus, the 
standard system can be easily modified to any non-standard 
environment by changing the peripheral drivers to handle the 
custom system. 

An Overview of CP/M 2.0 Facilities 



CP/M 2.0 is a high-performance single-console operating system 
which uses table driven techniques to allow field configuration to 
match a wide variety of disk capacities. All of the fundamental file 
restrictions are removed, while maintaining upward compatibility 
from previous versions of release 1 . Features of CP/M 2.0 include 
field specification of one to sixteen logical drives, each containing 
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up to eight megabytes. Any particular file can reach the full drive 
size with the capability to expand to thirty-two megabytes in future 
releases. The directory size can be field configured to contain any 
reasonable number of entries, and each file is optionally tagged 
with read/only and system attributes. Users of CP/M 2.0 are 
physically separated by user numbers, with facilities for file copy 
operations from one user area to another. Powerful relative-record 
random access functions are present in CP/M 2.0 which provide 
direct access to any of the 65536 records of an eight megabyte file. 

All disk-dependent portions of CP/M 2.0 are placed into a BIOS- 
resident "disk parameter block" which is either hand coded or 
produced automatically using the disk definition macro library 
provided with CP/M 2.0. The end user need only specify the 
maximum number of active disks, the starting and ending sector 
numbers, the data allocation size, the maximum extent of the 
logical disk, directory size information, and reserved track values. 
The macros use this information to generate the appropriate tables 
and table references for use during CP/M 2.0 operation. Deblocking 
information is also provided which aids in assembly or disassembly 
of sector sizes which are multiples of the fundamental 128 byte 
data unit, and the system alteration manual includes general-purpose 
subroutines which use this deblocking information to take advantage 
of larger sector sizes. Use of these subroutines, together with the 
table driven data access algorithms, make CP/M 2.0 truly a universal 
data management system. 

File expansion is achieved by providing up to 512 logical file 
extents, where each logical extent contains 16K bytes of data. 
CP/M 2.0 is structured, however, so that as much as 1 28K bytes of 
data is addressed by a single physical extent (corresponding to a 
single directory entry), thus maintaining compatibility with previous 
versions while taking full advantage of directory space. 

Random access facilities are present in CP/M 2.0 which allow 
immediate reference to any record of an eight megabyte file. Using 
CP/M's unique data organization, data blocks are only allocated 
when actually required and movement to a record position requires 
little search time. Sequential file access is upwardly compatible 
from earlier versions to the full eight megabytes, while random 
access compatibility stops at 51 2K byte files. Due to CP/M 2.0's 
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simpler and faster random access, application programmers are 
encouraged to alter their programs to take full advantage of the 2.0 
facilities. 

Several CP/M 2.0 modules and utilities have improvements which 
correspond to the enhanced file system. STAT and PIP both account 
for file attributes and user areas, while the CCP provides a "login" 
function to change from one user area to another. The CCP also 
formats directory displays in a more convenient manner and 
accounts for both CRT and hard-copy devices in its enhanced line 
editing functions. 

Functional Description of CP/M 



The user interacts with CP/M primarily through the CCP, which 
reads and interprets commands entered through the console. In 
general, the CCP addresses one of several disks which are online 
(the standard system addresses up to four different disk drives). 
These disk drives are labelled A, B, C, and D. A disk is "logged in" if 
the CCP is currently addressing the disk. In order to clearly 
indicate which disk is the currently logged disk, the CCP always 
prompts the operator with the disk name followed by the symbol 
">" indicating that the CCP is ready for another command. Upon 
initial start up, the CP/M system is brought in from disk A, and 
the CCP displays the message 

xxK CP/M VER m.m 

where xx is the memory size (in kilobytes) which this CP/M system 
manages, and m.m is the CP/M version number. Following system 
signon, CP/M automatically logs in disk A, prompts the user with 
the symbol "A>" (indicating that CP/M is currently addressing 
disk "A"), and waits for a command. The commands are implemented 
to two levels: built-in commands and transient commands. 
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General Command Structure 



Built-in commands are a part of the CCP program itself, while 
transient commands are loaded into the TPA from disk and 
executed. The built-in commands are 



ERA 


Erase specified files. 


DIR 


Displays file names in the directory. 


REN 


Rename the specified file. 


SAVE 


Save memory contents in a file. 


TYPE 


Type the contents of a file on the logged disk. 


USER 


Move to another area within the same 




directory. 



Nearly all of the commands reference a particular file or group of 
files. The form of a file reference is specified below. 

File References 



A file reference identifies a particular file or group of files on a 
particular disk attached to CP/M. These file references can be 
either "unambiguous" (ufn) or "ambiguous" (afn). An unambiguous 
file reference uniquely identifies a single file, while an ambiguous 
file reference may be satisfied by a number of different files. 

File references consist of two parts: the primary name and the 
secondary name. Although the secondary name is optional, it 
usually is generic; that is, the secondary name "ASM," for 
example, is used to denote that the file is an assembly language 
source file, while the primary name distinguishes each particular 
source file. The two names are separated by a "." as shown below: 

pppppppp.sss 

Where pppppppp represents the primary name of eight characters 
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or less, and sss is the secondary name of no more than three 
characters. As mentioned above, the name 

pppppppp 

is also allowed and is equivalent to a secondary name consisting 
of three blanks. The characters used in specifying an unambiguous 
file reference cannot contain any of the special characters 

<>.,;: = ?*[] 

while all alphanumerics and remaining special characters are 
allowed. 

An ambiguous file reference is used for directory search and 
pattern matching. The form of an ambiguous file reference is 
similar to an unambiguous reference, except the symbol "?" may 
be interspersed throughout the primary and secondary names. In 
various commands throughout CP/M, the "?" symbol matches any 
character of a file name in the "?" position. Thus, the ambiguous 
reference 

X?Z.C?M 

is satisfied by the unambiguous file names 
XYZ.COM 

and 

X3Z.CAM 
Note that the ambiguous reference 

is equivalent to the ambiguous file reference 
???????? ??? 
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while 

pppppppp* 

and 

*.sss 

are abbreviations for 
pppppppp.??? 

and 

.????????. sss 
respectively. As an example, 
DIR *.* 

is interpreted by the CCP as a command to list the names of all disk 
files in the directory, while 

DIR X.Y 

searches only for a file by the name X.Y. Similarly, the command 
DIRX?Y.C?M 

causes a search for all (unambiguous) file names on the disk which 
satisfy this ambiguous reference. 

The following file names are valid unambiguous file references: 

X XYZ GAMMA 

X.Y XYZ.COM GAMMA. 1 

As an added convenience, the programmer can generally specify 
the disk drive name along with the file name. In this case, the drive 
name is given as a letter A through Z followed by a colon (:). The 
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specified drive is then "logged in" before the file operation occurs. 
Thus, the following are valid file names with disk name prefixes: 

A:X.Y B:XYZ C:GAMMA 

Z:XYZ.COM B:X.A?M C:*.ASM 

It should also be noted that all alphabetic lower case letters in file 
and drive names are always translated to upper case when they 
are processed by the CCP. 



Switching Disks 

The operator can switch the currently logged disk by typing the 
disk drive name (A, B, C, or D) followed by a colon (:) when the CCP 
is waiting for console input. Thus, the sequence of prompts and 
commands shown below might occur after the CP/M system is 
loaded from disk A: 

16KCP/M VER 1.4 

A>DIR List all files on disk A. 

SAMPLE ASM 
SAMPLE PRN 

A>B: Switch to disk B. 

B>Dir*.ASM List all "ASM" files on B. 

DUMP ASM 
FILES ASM 

B>A: Switch back to A. 



Form of Built-in Commands 



The file and device reference forms described above can now be 
used to. fully specify the structure of the built-in commands. In the 
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description below, assume the following abbreviations: 

ufn unambiguous file reference 

afn ambiguous file reference 

cr carriage return 

Further, recall that the CCP always translates lower case characters 
to upper case characters internally. Thus, lower case alphabetics 
are treated as if they are upper case in command names and file 
references. 



ERAse Command 

ERA afn 



The ERA (erase) command removes files from the currently 
logged-in disk (i.e., the disk name currently prompted by CP/M 
preceding the ">"). The files which are erased are those which 
satisfy the ambiguous file reference afn. The following examples 
illustrate the use of ERA: 



ERA X.Y The file named X.Y on the currently 

logged disk is removed from the disk 
directory, and the space is returned. 

ERA X.* All files with primary name X are 

removed from the current disk. 

ERA *.ASM All files with secondary name ASM 

are removed from the current disk. 

ERA X?Y.C?M All files on the current disk which 
satisfy the ambiguous reference 
X?Y.C?M are deleted. 

ERA *.* Erase all files in the current user's 

directory. (See USER, page 15.) The 
CCP prompts with the message 

ALL (Y/N)? 



which requires a Y response before 
files are actually removed. 
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ERA B:*.PRN All files on drive B which satisfy 
the ambiguous reference 

????????. PRN 

are deleted, independently of the 
currently logged disk. 

DIRectory Command 

DIR afn 

The DIR(directory) command causes the names of all files which 
satisfy the ambiguous file name afn to be listed at the console 
device. As a special case, the command 

DIR 

lists the files on the currently logged disk (the command "DIR" is 
equivalent to the command "DIR *.*"). Valid DIR commands are 
shown below. 

DIRX.Y 
DIR X?Z.C?M 
DIR ??.Y 

Similar to other CCP commands, the afn can be preceded by a 
drive name. The following DIR commands cause the selected 
drive to be addressed before the directory search takes place. 

DIR B: 
DIR B:X.Y 
DIR B:*.A?M 

If no files can be found on the selected diskette which satisfy the 
directory request, then the message "NOT FOUND" is typed at 
the console. 
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REName Command 



REN ufn2 = ufnl 



The REN (rename) command allows the user to change the 
names of files on disk. The file satisfying ufn2 is changed to ufnl . 
The currently logged disk is assumed to contain the file to 
rename (ufnl ). The CCP also allows the user to type a left-directed 
arrow instead of the equal sign, if the user's console supports the 
graphic character. Examples of the REN command are 

REN X.Y = Q.R The file Q.R is changed 

to X.Y. 

REN XYZ.COM = XYZ.XXX The file XYZ.XXX is 

changed to XYZ.COM. 

The operator can precede either ufnl or ufn2 (or both) by an 
optional drive address. Given that ufnl is preceded by a drive 
name, then ufn2 is assumed to exist on the same drive as ufnl . 
Similarly, if ufn2 is preceded by a drive name, then ufnl is assumed 
to reside on that drive as well. If both ufnl and ufn2 are preceded 
by drive names, then the same drive must be specified in both 
cases. The following REN commands illustrate this format. 



REN A:X.ASM = YASM 
REN B:ZAP.BAS = ZOT.BAS 
REN B:A.ASM = B:A.BAK 



The file YASM is 
changed to X.ASM on 
drive A. 

The file ZOT.BAS is 
changed to ZARBAS on 
drive B. 

The file A.BAK is 
renamed to A. ASM on 
drive B. 



If the file ufnl is already present, the REN command will respond 
with the error "FILE EXISTS" and not perform the change. If 
ufn2 does not exist on the specified diskette, then the message 
"NOT FOUND" is printed at the console. 
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SAVE Command 

SAVE n ufn 

The SAVE command places n pages (256-byte blocks) onto disk 
from the TPA and names this file ufn. In the CP/M distribution 
system, the TPA starts at 100H (hexadecimal), which is the 
second page of memory. Thus, if the user's program occupies the 
area from 100H through 2FFH, the SAVE command must specify 
two pages of memory. The machine code file can be subsequently 
loaded and executed. Examples are: 

SAVE 3 X.COM Copies 100H through 

3FFH to X.COM. 

SAVE 40 Q Copies 100H through 

28FFH to Q (note that 
28 is the page count in 
28FFH,and that 28H = 
2*16+8 = 40 decimal). 

SAVE 4 X.Y Copies 100H through 

4FFH to X.Y. 

The SAVE command can also specify a disk drive in the afn portion 
of the command, as shown below. 

SAVE 10 B:ZOT.COM Copies 10 pages (100H 

through OAFFH) to the 
file ZOT.COM on drive B 

The SAVE operation can be used any number of times without 
altering the memory image. 

TYPE Command 

TYPE ufn 

The TYPE command displays the contents of the ASCII source file 
ufn on the currently logged disk at the console device. Valid 
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TYPE commands are 

TYPE X.Y 
TYPE X.PLM 
TYPE XXX 

The TYPE command expands the tabs (ctl-l characters), assuming 
tab positions are set at every eighth column. The ufn can also 
reference a drive name as shown below. 

TYPE B:X.PRN The file X.PRN from 

drive B is displayed. 

USER Command 

USER n 

Where n is an integer value in the range to 15. 

Upon cold start, the operator is automatically "logged" into user 
area number 0. The operator may issue the USER command at any 
time to move to another logical area within the same directory. 

Drives which are logged in while addressing one user number 
are automatically active when the operator moves to another user 
number since a user number is simply a prefix which accesses 
particular directory entries on the active disks. 

The active user number is maintained until changed by a subsequent 
USER command, or until a cold start operation when user is 
again assumed. 

Line Editing and Output Control 



The CCP allows certain line editing functions while typing command 
lines. "Control" indicates that the Control key and the indicated key 
are to be pressed simultaneously. CCP commands can generally be 
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up to 255 characters in length; they are not acted upon until the 
carriage return key is pressed. 



rubout/delete 
Control C 
Control E 

Control H 



Control J 
Control M 
Control R 

Control X 



Remove and echo last character typed. 

Reboot CP/M when at beginning of line. 

Physical end of line: carriage is 
returned, but line is not sent until the 
carriage return key is depressed. 

Backspace one character position. 
Produces the backspace overwrite 
function. Can be changed internally 
to another character, such as delete, 
through a simple single byte change. 

Line feed. Terminates current input. 

Carriage return. Terminates input. 

Retype current command line after 
new line. 

Backspace to beginning of current line. 



The line editor keeps track of the current prompt column position 
so that the operator can properly align data input following a 
Control R or Control X command. 

The control functions Control P and Control S affect console output 
as shown below. 



Control P Copy all subsequent console output 

to the currently assigned list device 
(see the STAT command). Output is sent 
to both the list device and the console 
device until the next Control P is typed. 

Control S Stop the console output temporarily. 

Program execution and output continue 
when the next character is typed at 
the console (e.g., another Control S). 
This feature is used to stop output on 
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high speed consoles, such as CRT's, 
in order to view a segment of output 
before continuing. 



Transient Commands 



Transient commands are loaded from the currently logged disk and 
executed in the TPA. The transient commands defined for execution 
under the CCP are shown below. Additional functions can easily be 
defined by the user (see the LOAD command definition). 



STAT 



ASM 



LOAD 



DDT 
PIP 

ED 

SUBMIT 
DUMP 



List the number of bytes of storage 
remaining on the currently logged disk, 
provide statistical information about 
particular files, and display or alter 
device assignment. 

Load the CP/M assembler and 
assemble the specified program from 
disk. 

Load the file in Intel "hex" machine 
code format and produce a file in 
machine executable form which can be 
loaded into the TPA (this loaded 
program becomes a new command 
under the CCP). 

Load the CP/M debugger into TPA 
and start execution. 

Load the Peripheral Interchange 
Program for subsequent disk file and 
peripheral transfer operations. 

Load and execute the CP/M text 
editor program. 

Submit a file of commands for 
batch processing. 

Dump the contents of a file in hex. 
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Transient commands are specified in the same manner as built-in 
commands, and additional commands can be easily defined by the 
user. As an added convenience, the transient command can be 
preceded by a drive name, which causes the transient to be loaded 
from the specified drive into the TPA for execution. Thus, the 
command 

B:STAT 

causes CP/M to temporarily "log in" drive B for the source of the 
STAT transient, and then return to the original logged disk for 
subsequent processing. 

The basic transient commands are listed in detail below. 
STAT 

The STAT command provides general statistical information about 
file storage and device assignment. It is initiated by typing one of 
the following forms: 

STAT 

STAT "command line" 

Special forms of the "command line" allow the current device 
assignment to be examined and altered as well. The various 
command lines which can be specified are shown below, with an 
explanation of each form shown to the right. 

STAT <cr> If the user types an empty command 

line, the STAT transient calculates the 
storage remaining on all active drives, 
and prints a message 

x: R/W, SPACE: nnnK 

or 

x: R/O, SPACE: nnnK 

for each active drive x, where R/W 
indicates the drive may be read or 
written, and R/O indicates the drive 
is read only (a drive becomes R/O by 
explicitly setting it to read only, as 
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shown below, or by inadvertently changing 
diskettes without performing a warm 
start). The space remaining on the 
diskette in drive x is given in kilobytes 
by nnn. 

STAT x: <cr> If a drive name is given, then the drive 

is selected before the storage is 
computed. Thus, the command "STAT B:" 
could be issued while logged into drive 
A, resulting in the message 

BYTES REMAINING ON B: nnnK 

STAT afn <cr> The command line can also specify a set 

of files to be scanned by STAT. The files 
which satisfy afn are listed in alphabetical 
order, with storage requirements for each 
file under the heading 

RECS BYTS EX D:FILENAME.TYP 
rrrr bbbK ee d:pppppppp.sss 

where rrrr is the number of 128-byte 
records allocated to the file, bbb is the 
number of kilobytes allocated to the file 
(bbb=rrrr*1 28/1 024), ee is the number of 
16K extensions (ee=bbb/16), d is the 
drive name containing the file (A...Z), 
pppppppp is the (up to) eight-character 
primary file name, and sss is the 
(up to) three-character secondary name. 
After listing the individual files, the 
storage usage is summarized. 

STAT x:afn <cr> As a convenience, the drive name can 

be given ahead of the afn. In this case, 
the specified drive is first selected, and 
the form "STAT afn" is executed. 
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STAT d:filename.typ $S<cr> 

("d:" is optional drive Produces the output display format: 
name and 

"filename. typ" is Size Recs Bytes Ext Acc 

an unambiguous or 
ambiguous file 
name) 



48 48 6K 1 R/O A:ED.COM 
55 55 12K 1 R/O (A:PIP.COM) 
65536 128 2K 2 R/WA:X.DAT 



The $S parameter causes the "Size" 
field to be displayed. (The command 
may be used without the $S if desired.) 
The Size field lists the virtual file size 
in records, while the "Recs" field sums 
the number of virtual records in each 
extent. For files constructed sequentially, 
the Size and Recs fields are identical. 
The "Bytes" field lists the actual number 
of bytes allocated to the corresponding 
file. The minimum allocation unit is 
determined at configuration time, and 
thus the number of bytes corresponds to 
the record count plus the remaining 
unused space in the last allocated 
block for sequential files. Random access 
files are given data areas only when 
written, so the Bytes field contains the 
only accurate allocation figure. In the 
case of random access, the Size field 
gives the logical end-of-file record 
position and the Recs field counts the 
logical records of each extent (each of 
these extents, however, may contain 
unallocated "holes" even though they 
are added into the record count). The 
"Ext" field counts the number of local 
16K extents allocated to the file. The 
"Acc" field gives the R/O or R/W access 
mode, which is changed using the 
commands shown below. The parentheses 
shown around the PIP.COM file name 
indicate that it has the "system" 
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indicator set, so that it will not be 
listed in DIR commands. 

STAT d:filename.typ $R/0 <cr> 

Places the file or set of files in a 
read-only status until changed by a 
subsequent STAT command. The R/O 
status is recorded in the directory with the 
file so that it remains R/O through 
intervening cold start operations. When a 
file is marked R/O, attempts to erase or 
write into the file result in a terminal BDOS 
message: Bdos Err on D: File R/O. 

STAT d:filename.typ $R/W <cr> 

Places the file in a permanent 
read/write status. 

STAT d:filename.typ $SYS <cr> 

Attaches the system indicator to the file. 

STATd.filename.typ $DIR <cr> 

Removes the system indicator from the file. 

STAT d:DSK: <cr> Lists the drive characteristics of the disk 

named by "d:" which is in the range 

A:, B: P:. The drive characteristics 

are listed in the format: 



d 

65536 
8192 
128 


1024 
128 
58 
2 



Drive Characteristics 
128 Byte Record Capacity 
Kilobyte Drive Capacity 
32 Byte Directory Entries 
Checked Directory Entries 
Records/Extent 
Records/Block 
Sectors/Track 
Reserved Tracks 



The total record capacity is listed, followed 
by the total drive capacity listed in Kbytes. 
The number of checked entries is usually 
identical to the directory size for removable 
media, since this mechanism is used to 
detect changed media during CP/M 
operation without an intervening warm 
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start. The number of records per extent 
determines the addressing capacity of 
each directory entry (1024 times 128 bytes, 
or 128K in the example above). The 
number of records per block shows the 
basic allocation size (in the example, 128 
records/block times 128 bytes per record, 
or 16K bytes per block). The listing is then 
followed by the number of physical sectors 
per track and the number of reserved 
tracks. 

STAT DSK: <cr> Lists drive characteristics as above for all 

currently active drives. 

STAT USR: <cr> Produces a list of the user numbers which 

have files on the currently addressed disk. 
The display format is: 

Active User: 
Active Files: 1 3 

where the first line lists the currently 
addressed user number, as set by the last 
CCP USER command, followed by a list of 
user numbers scanned from the current 
directory. In the above case, the active 
user number is (default at cold start), 
with three user numbers which have active 
files on the current disk. The operator can 
subsequently examine the directories of 
the other user numbers by logging in with 
USER 1 , USER 2, or USER 3 commands, 
followed by a DIR command at the CCP 
level. 

The STAT command also allows control over the physical to logical 
device assignment (see the IOBYTE function described in the 
"CP/M Interface Guide"). In general, there are four logical peripheral 
devices which are, at any particular instant, each assigned to one of 
several physical peripheral devices. The four logical devices are 
named: 

CON: The system console device (used by CCP 

for communication with the operator) 
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RDR: The paper tape reader device 

PUN: The paper tape punch device 

LST: The output list device 

The actual devices attached to any particular computer system are 
driven by subroutines in the BIOS portion of CP/M. Thus, the 
logical RDR: device, for example, could actually be a high speed 
reader, Teletype reader, or cassette tape. In order to allow some 
flexibility in device naming and assignment, several physical devices 
are defined, as shown below: 



TTY: Teletype device (slow speed console) 

CRT: Cathode ray tube device 
(high speed console) 

BAT: Batch processing (console is current 

RDR:, output goes to current LST: device) 

UC1: User-defined console 

PTR: Paper tape reader (high speed reader) 

UR1: User-defined reader #1 

UR2: User-defined reader #2 

PTP: Paper tape punch (high speed punch) 

UP1: User-defined punch #1 

UP2: User-defined punch #2 

LPT: Line printer 

UL1 : User-defined list device #1 



It must be emphasized that the physical device names may or may 
not actually correspond to devices which the names imply. That is, 
the PTP: device may be implemented as a cassette write operation, 
if the user wishes. The exact correspondence and driving subroutine 
is defined in the BIOS portion of CP/M. 
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The command: 

STAT VAL: <cr> 

produces a summary of the available status commands, resulting in 
the output: 

Temp R/O Disk: d: = R/O 

Set Indicator: d:filename.typ $R/0 $R/W $SYS $DIR 



Disk Status: 


DSK: 


d:DSK: 




User Status: 


USR: 






lobyte Assign: 








CON. = TTY: 


CRT: 


BAT: 


UC1 


RDR: = TTY: 


PTR: 


UR1: 


UR2 


PUN: = TTY: 


PTP: 


UP1: 


UP2 


LST: = TTY: 


CRT: 


LPT: 


UL1: 



In each case, the logical device shown to the left can take any of 
the four physical assignments shown to the right on each line. The 
current logical to physical mapping is displayed by typing the 
command 

STAT DEV: <cr> 

which produces a listing of each logical device to the left, and the 
current corresponding physical device to the right. For example, 
the list might appear as follows: 

CON: = CRT: 
RDR: = UR1: 
PUN: = PTP: 
LST: = TTY: 

The current logical to physical device assignment can be changed by 
typing a STAT command of the form 

STAT Id1 = pd1 , Id2 = pd2 Idn = pdn <cr> 

where Id1 through Idn are logical device names, and pd1 through 
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pdn are compatible physical device names (i.e., Idi and pdi appear on 
the same line in the "VAL:" command shown above). The 
following are valid STAT commands which change the current logical 
to physical device assignments: 

STAT CON: = CRT: cr 

STAT PUN: - TTY:, LST: - LPT:, RDR: = TTY: cr 

ASM ufn 

The ASM command loads and executes the CP/M 8080 assembler. 
The ufn specifies a source file containing assembly language 
statements where the secondary name is assumed to be ASM, and 
thus is not specified. The following ASM commands are valid: 

ASM X 

ASM GAMMA 

The two-pass assembler is automatically executed. If assembly 
errors occur during the second pass, the errors are printed at the 
console. 

The assembler produces a file 
x.PRN 

where x is the primary name specified in the ASM command. The 
PRN file contains a listing of the source program (with imbedded 
tab characters if present in the source program), along with the 
machine code generated for each statement and diagnostic error 
messages, if any. The PRN file can be listed at the console using 
the TYPE command, or sent to a peripheral device using PIP 
(see the PIP command structure below). Note also that the PRN file 
contains the original source program, augmented by 
miscellaneous assembly information in the leftmost 16 columns 
(program addresses and hexadecimal machine code, for example). 
Thus, the PRN file can serve as a backup for the original source 
file: if the source file is accidentally removed or destroyed, the 
PRN file can be edited (see the ED operator's guide) by removing 
the leftmost 16 characters of each line (this can be done by issuing 
a single editor "macro" command). The resulting file is identical 
to the original source file and can be renamed (REN) from PRN to 
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ASM for subsequent editing and assembly. The file 
x.HEX 

is also produced which contains 8080 machine language in Intel 
"hex" format suitable for subsequent loading and execution (see 
the LOAD command). For complete details of CP/M s assembly 
language program, see the "CP/M Assembler Language (ASM) 
User's Guide." 

Similar to other transient commands, the source file for assembly 
can be taken from an alternate disk by prefixing the assembly 
language file name by a disk drive name. Thus, the command 

ASM B.ALPHA <cr> 

loads the assembler from the currently logged drive and operates 
upon the source program ALPHA. ASM on drive B. The HEX and 
PRN files are also placed on drive B in this case. 

LOAD ufn cr 

The LOAD command reads the file ufn, which is assumed to 
contain "hex" format machine code, and produces a memory 
image file which can be subsequently executed. The file name ufn 
is assumed to be of the form 

x.HEX 

and thus only the name x need be specified in the command. 
The LOAD command creates a file named 

x.COM 

which marks it as containing machine executable code. The file is 
actually loaded into memory and executed when the user types 
the file name x immediately after the prompting character ">" 
printed by the CCP 

In general, the CCP reads the name x following the prompting 
character and looks for a built-in function name. If no function 
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name is found, the CCP searches the system disk directory for a 
file by the name 

x.COM 

If found, the machine code is loaded into the TPA, and the 
program executes. Thus, the user need only LOAD a hex file once, 
it can be subsequently executed any number of times by simply 
typing the primary name. In this way, the user can "invent new 
commands in the CCP. (Initialized disks contain the transient 
commands as COM files, which can be deleted at the user s 
option.) The operation can take place on an alternate drive if the 
file name is prefixed by a drive name. Thus 

LOAD B:BETA 

brings the LOAD program into the TPA from the currently logged 
disk and operates upon drive B after execution begins. 

It must be noted that the BETA. HEX file must contain valid Intel 
format hexadecimal machine code records (as produced by the 
ASM program, for example) which begin at 100H, the beginning 
of the TPA. Further, the addresses in the hex records must be in 
ascending order; gaps in unfilled memory regions are filled with 
zeroes by the LOAD command as the hex records are read. Thus, 
LOAD must be used only for creating CP/M standard ' COM files 
which operate in the TPA. Programs which occupy regions of 
memory other than the TPA can be loaded under DDT. 

PIP 

PIP is the CP/M Peripheral Interchange Program which implements 
the basic media conversion operations necessary to load, print 
punch, copy, and combine disk files. The PIP program is initiated by 
typing one of the following forms 

PIP<cr> 

PIP "command line" <cr> 

In both cases, PIP is loaded into the TPA and executed. In case 1 , 
PIP reads command lines directly from the console, prompted 
with the "*" character, until an empty command line is typed (i.e., a 
single carriage return is issued by the operator). Each successive 
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command line causes some media conversion to take place 
according to the rules shown below. Form 2 of the PIP command 
is equivalent to the first, except that the single command line given 
with the PIP command is automatically executed, and PIP 
terminates immediately with no further prompting of the console 
for input command lines. The form of each command line is 

destination = source #1 , source #2, source #n <cr> 

where "destination is the file or peripheral device to receive the 
data, and "source #1 , source #n" represents a series of one or 
more files or devices which are copied from left to right to the 
destination. 

When multiple files are given in the command line (i.e., n>1 ), the 
individual files are assumed to contain ASCII characters, with an 
assumed CP/M end-of-file character (ctl-Z) at the end of each file 
(see the O parameter to override this assumption). The equal 
symbol (=) can be replaced by a left-oriented arrow, if your console 
supports this ASCII character, to improve readability. Lower case 
ASCII alphabetics are internally translated to upper case to be 
consistent with CP/M file and device name conventions. Finally, 
the total command line length cannot exceed 255 characters (ctl-E 
can be used to force a physical carriage return for lines which 
exceed the console width). 

The destination and source elements can be unambiguous 
references to CP/M source files, with or without a preceding disk 
drive name. That is, any file can be referenced with a preceding 
drive name (A:, B:, C:, or D:) which defines the particular drive 
where the file may be obtained or stored. When the drive name 
is not included, the currently logged disk is assumed. Further, the 
destination file can also appear as one or more of the source 
files, in which case the source file is not altered until the entire 
concatenation is complete. If the destination file already exists, it 
is removed if the command line is properly formed (it is not 
removed if an error condition arises). The following command 
lines (with explanations to the right) are valid as input to PIP: 



X = Y <cr> 



Copy to file X from file Y, where 
X and Y are unambiguous file 
names; Y remains unchanged. 
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X = Y,Z <cr> 

X.ASM = Y.ASM,Z.ASM,FIN.ASM 

NEW.ZOT= B:OLD.ZAP<cr> 
B:A.U. = B:B.V,A:C.W,D.X<cr> 



Concatenate files Y and Z and 
copy to file X, with Y and 
Z unchanged. 

<cr> 

Create the file X.ASM from the 
concatenation of the Y, Z, and 
FIN files with type ASM. 

Move a copy of OLD. ZAP from 
drive B to the currently logged 
disk; name the file NEW.ZOT. 

Concatenate file B.V from drive 
B with C.W from drive A and 
D.X. from the logged disk; 
create the file A.U on 
drive B. 



For more convenient use, PIP allows abbreviated commands for 
transferring files between disk drives. The abbreviated forms are 

PIPx: = afn <cr> 
PIP x: = y:afn <cr> 
PIP ufn = y: <cr> 
PIP x:ufn = y: <cr> 

The first form copies all files from the currently logged disk 
which satisfy the afn to the same file names on drive x (x = A...Z). 
The second form is equivalent to the first, where the source for 
the copy is drive y (y = A...Z). The third form is equivalent to the 
command "PIP ufn = y:ufn <cr>" which copies the file given by 
ufn from drive y to the file ufn on drive x. The fourth form is 
equivalent to the third, where the source disk is explicitly given 
byy. 

Note that the source and destination disks must be different in 
all of these cases. If an afn is specified, PIP lists each ufn which 
satisfies the afn as it is being copied. If a file exists by the same 
name as the destination file, it is removed upon successful 
completion of the copy, and replaced by the copied file. 
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The following PIP commands give examples of valid disk-to-disk 
copy operations: 



B: = *.COM <cr> Copy all files which have the 

secondary name "COM" to drive 
B from the current drive. 

A: = B:ZAP* <cr> Copy all files which have the 

primary name "ZAP" to drive 
A from drive B. 

ZAP.ASM = B: <cr> Equivalent to 

ZAP.ASM = B:ZAP.ASM 

B:ZOT.COM = A: <cr> Equivalent to 

B:ZOT.COM = A:ZOT.COM 

B: = GAMMA. BAS <cr> Same as 

B:GAMMA.BAS = GAMMA. BAS 

B: = A:GAMMA.BAS <cr> Same as 

B:GAMMA.BAS = A:GAMMA.BAS 



PIP also allows reference to physical and logical devices which are 
attached to the CP/M system. The device names are the same as 
given under the STAT command, along with a number of specially 
named devices. The logical devices given in the STAT command are 

CON: (console), RDR: (reader), PUN: (punch), and LST: (list) 



while the physical devices are 



TTY: (console, reader, punch, or list) 
CRT: (console, or list), UC1 : (console) 

PTR: (reader), UR1 : (reader), UR2: (reader) 
PTP: (punch), UP1: (punch), UP2: (punch) 
LPT: (list), UL1 : (list) 



(Note that the "BAT:" physical device is not included, since this 
assignment is used only to indicate that the RDR: and LST: devices 
are to be used for console input/output.) 

The RDR, LST, PUN, and CON devices are all defined within the 
BIOS portion of CP/M. (The current physical device mapping is 



Introduction 31 



defined by IOBYTE; see the "CP/M Interface Guide" for a 
discussion of this function.). The destination device must be capable 
of receiving data (i.e., data cannot be sent to the punch), and the 
source devices must be capable of generating data (i.e., the LST: 
device cannot be read). 

The additional device names which can be used in PIP commands 
are 

NUL: Send 40 "nulls" (ASCII 0's) to the device (this 
can be issued at the end of punched output). 

EOF: Send a CP/M end-of-file (ASCII ctl-Z) to the 

destination device (sent automatically at the end 
of all ASCII data transfers through PIP). 

INP: Special PIP input source which can be "patched" 
into the PIP program itself: PIP gets the input data 
character-by-character by CALLing location 
103H, with data returned in location 109H (parity 
bit must be zero). 

OUT: Special PIP output destination which can be 

patched into the PIP program: PIP CALLs location 
106H with data in register C for each character 
to transmit. Note that locations 109H through 
1 FFH of the PIP memory image are not used and 
can be replaced by special purpose drivers 
using DDT (see the DDT operator's manual). 

PRN: Same as LST:, except that tabs are expanded 
at every eighth character position, lines are 
numbered, and page ejects are inserted every 
60 lines, with an initial eject (same as [t8np]). 

File and device names can be interspersed in the PIP commands. 
In each case, the specific device is read until end-of-file (ctl-Z for 
ASCII files, and a real end of file for non-ASCII disk files). Data 
from each device or file is concatenated from left to right until 
the last data source has been read. The destination device or file is 
written using the data from the source files, and an end-of-file 
character (ctl-Z) is appended to the result for ASCII files. Note that 
if the destination is a disk file, a temporary file is created ($$$ 
secondary name) which is changed to the actual file name only 
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upon successful completion of the copy. Files with the extension 
"COM" are always assumed to be non-ASCII. 

The copy operation can be aborted at any time by depressing any 
key on the keyboard (a rubout suffices). PIP will respond with the 
message "ABORTED" to indicate that the operation was not 
completed. Note that if any operation is aborted, or if an error 
occurs during processing, PIP removes any pending commands 
which were set up while using the SUBMIT command. 

It should also be noted that PIP performs a special function if the 
destination is a disk file with type "HEX" (an Intel hex formatted 
machine code file), and the source is an external peripheral 
device, such as a paper tape reader. In this case, the PIP program 
checks to ensure that the source file contains a properly formed 
hex file, with legal hexadecimal values and checksum records. 
When an invalid input record is found, PIP reports an error 
message at the console and waits for corrective action. For 
convenience, PIP allows the end-of-file to be entered from the 
console if the source file is a RDR: device. In this case, the PIP 
program reads the device and monitors the keyboard. If ctl-Z is 
typed at the keyboard, then the read operation is terminated 
normally. 

Valid PIP commands are shown below. 

PIP LST: = X.PRN <cr> Copy X.PRN to the LST device and 

terminate the PIP program. 

PIP <cr> Start PIP for a sequence of commands 

(PIP prompts with "*"). 

*CON: = X.ASM,Y.ASM,Z.ASM <cr> 

Concatenate three ASM files and 
copy to the CON device. 

*X.HEX = CON:,Y.HEX,PTR: <cr> 

Create a HEX file by reading CON 
(until a ctl-Z is typed), followed by 
data from Y.HEX, followed by data 
from PTR until a ctl-Z is encountered. 



*<cr> 



Single carriage return stops PIP. 
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PIP PUN: = NUL:,X.ASM,EOF:,NUL: <cr> 

Send 40 nulls to the punch device; 
then copy the X.ASM file to the 
punch, followed by an end-of-file 
(ctl-Z) and 40 more null characters. 

The user can also specify one or more PIP parameters, enclosed in 
left and right square brackets, separated by zero or more blanks. 
Each parameter affects the copy operation, and the enclosed list of 
parameters must immediately follow the affected file or device. 
Generally, each parameter can be followed by an optional decimal 
integer value (the S and Q parameters are exceptions). The valid 
PIP parameters are listed below. 

B Block mode transfer: data is buffered by PIP until 

an ASCII x-off character (ctl-S) received from the 
source device. This allows transfer of data to a 
disk file from a continuous reading device, such 
as a cassette reader. Upon receipt of the x-off, 
PIP clears the disk buffers and returns for more 
input data. The amount of data which can be 
buffered is dependent upon the memory size of 
the host system (PIP will issue an error message 
if the buffers overflow). 

Dn Delete characters which extend past column n in 

the transfer of data to the destination from the 
character source. This parameter is used most 
often to truncate long lines which are sent to a 
(narrow) printer or console device. 

E Echo all transfer operations to the console as 

they are being performed. 

F Filter form feeds from the file. All imbedded 

form feeds are removed. The P parameter can be 
used simultaneously to insert new form feeds. 
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Gn Get file from user number n. (n is the range 

0-15.) Allows one user area to receive data files 
from another. If the operator has issued the 
USER 4 command at the CCP level, the 
PIP statement 

PIPX.Y = X.Y[G2] 

reads file X.Y from user number 2 into user area 
number 4. You cannot copy files into a different 
area than the one which is currently addressed 
by the USER command. 

H Hex data transfer: all data is checked for proper 

Intel hex file format. Non-essential characters 
between hex records are removed during the 
copy operation. The console will be prompted for 
corrective action in case errors occur. 

I Ignore ":00" records in the transfer of Intel 

hex format file (the I parameter automatically 
sets the H parameter). 

L Translate upper case alphabetics to lower case. 

N Add line numbers to each line transferred to 

the destination, starting at one, and incrementing 
by 1. Leading zeroes are suppressed, and the 
number is followed by a colon. If N2 is specified, 
then leading zeroes are included, and a tab is 
inserted following the number. The tab is 
expanded if T is set. 

O Object file (non-ASCII) transfer: the normal 

CP/M end of file is ignored. 

Pn Include page ejects at every n lines (with an 

initial page eject). If n = 1 or is excluded 
altogether, page ejects occur every 60 lines. If 
the F parameter is used, form feed suppression 
takes place before the new page ejects are 
inserted. 

QsTz Quit copying from the source device or file 
when the string s (terminated by ctl-Z) is 
encountered. 
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R Read system files. Allows files with the system 

attribute to be included in PIP transfers. 
Otherwise, system files are not recognized. 

SsTz Start copying from the source device when 

the string s is encountered (terminated by ctl-Z). 
The S and Q parameters can be used to 
"abstract" a particular section of a file (such as 
a subroutine). The start and quit strings are always 
included in the copy operation. 



Note 

The strings following the s and q parameters are translated 
to upper case by the CCP if form (2) of the PIP command 
is used. Form (1 ) of the PIP invocation, however, does not 
perform the automatic upper case translation. 

(1 ) PIP <cr> 

(2) PIP "command line" <cr> 

Tn Expand tabs (ctl-l characters) to every nth column 

during the transfer of characters to the 
destination from the source. 

U Translate lower case alphabetics to upper case 

during the copy operation. 

V Verify that data has been copied correctly by 

rereading after the write operation (the 
destination must be a disk file). 

W Write over R/O files without console interrogation. 

Under a normal operation, PIP will not 
automatically overwrite a file which is set to 
a permanent R/O status. It advises the user of 
the R/O status and waits for overwrite approval. 
W allows the user to bypass this interrogation 
process. 

Z Zero the parity bit on input for each 

ASCII character. 
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The following are valid PIP commands which specify parameters 
in the file transfer: 

PIP X.ASM = B:[v] cr Copy X.ASM from drive B to the 

current drive and verify that the data 
was properly copied. 

PIPLST: = X.ASM[nt8u] <cr> 

Copy X.ASM to the LST: device; 
number each line, expand tabs to 
every eighth column, and translate 
lower case alphabetics to upper case. 

PIP PUN: = X.HEX[i],Y.ZOT[h] cr 

First copy X.HEX to the PUN: device 
and ignore the trailing ":00" record 
in X.HEX; then continue the transfer 
of data by reading Y.ZOT, which 
contains hex records, including any 
":00" records which it contains. 

PIPX.LIB = Y.ASM [sSUBR1:TzqJMP I 3 z j cr 

Copy from the file Y.ASM into the file 
X.LIB. Start the copy when the string 
"SUBR1 :" has been found, and quit 
copying after the string "JMP L3" is 
encountered. 

PIP LST: = X.ASM[p50] Send X.ASM to the LST: device, with 

line numbers, tabs expanded to every 
eighth column, and page ejects at 
every 50th line. Note that nt8p60 is 
the assumed parameter list for a LST 
file; p50 overrides the default value. 

Note that the PIP program itself is initially copied to a user area (so 
that subsequent files can be copied) using the SAVE command. 
The sequence of operations shown below effectively moves PIP 
from one user area to the next. 
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USER 
DDT PIP.COM 
(note PIP size s) 
GO 

USER 3 

SAVE s PIP.com 



login user 

load PIP in memory 

return to CCP 
login user 3 



where s is the integral number of memory "pages" (256 byte 
segments) occupied by PIP. The number s can be determined 
when PIP.COM is located under DDT, by referring to the value 
under the "NEXT" display. If for example, the next available 
address is 1D00, then PIP.COM requires 1C hexadecimal pages ( 
1 times 16+12 = 28 pages), and thus the value of s is 28 in the 
subsequent save. Once PIP is copied in this manner, it can then t 
copied to another disk belonging to the same user number 
through normal PIP transfers. 



ED 

The ED program is the CP/M system context editor, which allows 
creation and alteration of ASCII files in the CP/M environment. 
Complete details of operation are given in Chapter 3 CP/M ED. In 
general, ED allows the operator to create and operate upon 
source files which are organized as a sequence of ASCII characters, 
separated by end-of-line characters (a carriage-return line-feed 
sequence). There is no practical restriction on line length (no single 
line can exceed the size of the working memory), which is 
instead defined by the number of characters typed between <cr^ s. 
The ED program has a number of commands for character string 
searching, replacement, and insertion, which are useful in the 
creation and correction of programs or text files under CP/M. 
Although the CP/M has a limited memory work space area, 
the file size which can be edited is not limited, since data is easily 
"paged" through this work area. 

Upon initiation, ED creates the specified source file, if it does not 
exist, and opens the file for access. The programmer then 
"appends" data from the source file into the work area, if the 
source file already exists (see the A command), for editing. The 
appended data can then be displayed, altered, and written from the 
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work area back to the disk (see the W command). Particular 
points in the program can be automatically paged and located by 
context (see the N command), allowing easy access to particular 
portions of a large file. 

Given that the operator has typed 

ED X.ASM <cr> 

the ED program creates an intermediate work file with the name 
X.$$$ 

to hold the edited data during the ED run. Upon completion of ED, 
the X.ASM file (original file) is renamed to X.BAK, and the edited 
work file is renamed to X.ASM. Thus, the X.BAK file contains the 
original (unedited) file, and the X.ASM file contains the newly 
edited file. The operator can always return to the previous version 
of a file by removing the most recent version, and renaming the 
previous version. Suppose, for example, that the current X.ASM 
file was improperly edited; the sequence of CCP commands 
shown below would reclaim the backup file. 

DIRX.* Check to see that BAK file is 

available. 

ERA X.ASM Erase most recent version. 

REN X.ASM = X.BAK Rename the BAK file to ASM. 

Note that the operator can abort the edit at any point (reboot, 
power failure, ctl-C, or Q command) without destroying the original 
file. In this case, the BAK file is not created, and the original file 
is always intact. 

The ED program also allows the user to "ping-pong" the source and 
create backup files between two disks. The form of the ED 
command in this case is 

ED ufn d: 

where ufn is the name of a file to edit on the currently logged disk 
and d is the name of an alternate drive. The ED program reads 
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and processes the source file, and writes the new file to drive d, 
using the name ufn. Upon completion of processing, the original 
file becomes the backup file. Thus, if the operator is addressing 
disk A, the following command is valid: 

ED X.ASM B: 

which edits the file X.ASM on drive A, creating the new file 
X.$$$ on drive B. Upon completion of a successful edit, A:X.ASM is 
renamed to A:X.BAK, and B:X.$$$ is renamed to B:X.ASM. For 
user convenience, the currently logged disk becomes drive B at 
the end of the edit. Note that if a file by the name B.X.ASM 
exists before the editing begins, the message 

FILE EXISTS 

is printed at the console as a precaution against accidentally 
destroying a source file. In this case, the operator must first 
ERAse the existing file and then restart the edit operation. 

Similar to other transient commands, editing can take place on a 
drive different from the currently logged disk by preceding the 
source file name by a drive name. Examples of valid edit requests 
are shown below 

ED A:X.ASM Edit the file X.ASM on drive A, 

with new file and backup on 
drive A. 

ED B:X.ASM A: Edit the file X.ASM on drive B 

to the temporary file X.$$$ on 
drive A. On termination of 
editing, change X.ASM on drive 
B to X.BAK, and change X.$$$ 
on drive A to X.ASM. 

ED takes file attributes into account. If the operator attempts to 
edit a read/only file, the message 

**FILE IS READ/ONLY** 

appears at the console. The file can be loaded and examined, but 
cannot be altered in any way. Normally the operator simply ends 
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the edit session, and uses STAT to change the file attribute to R/W. 
If the edited file has the system attribute set, the message 

"SYSTEM" FILE NOT ACCESSIBLE 

is displayed at the console, and the edit session is aborted. 
Again, the STAT program can be used to change the system 
attribute if desired. 

SUBMIT 

The SUBMIT command allows CP/M commands to be batched 
together for automatic processing. The format of SUBMIT is: 

SUBMIT ufn parm #1 ...parm #n<cr> 

The ufn given in the SUBMIT command must be the filename of 
a file which exists on the currently logged disk, with an assumed 
file type of "SUB." The SUB file contains CP/M prototype 
commands, with possible parameter substitution. The actual 
parameters parm #1 ... parm #n are substituted into the prototype 
commands, and, if no errors occur, the file of substituted 
commands is processed sequentially by CP/M. 

The prototype command file is created using the ED program, with 
interspersed "$" parameters of the form 

$1 $2 $3 ... $n 

corresponding to the number of actual parameters which will be 
included when the file is submitted for execution. When the SUBMIT 
transient is executed, the actual parameters parm #1 ... parm #n 
are paired with the formal parameters $1 ...$n in the prototype 
commands. If the number of formal and actual parameters does 
not correspond, then the submit function is aborted with an error 
message at the console. The SUBMIT function creates a file of 
substituted commands with the name 

$$$.SUB 

on the logged disk. When the system reboots (at the termination of 
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the SUBMIT) this command file is read by the CCP as a source 
of input rather than the console. If the SUBMIT function is 
performed on any disk other than drive A, the commands are not 
processed until the disk is inserted into drive A and the system 
reboots Further the user can abort command processing at any 
time by typing a rubout when the command is read and echoed. In 
this case the $$$ SUB file is removed, and the subsequent 
commands come from the console. Command processing is also 
aborted if the CCP detects an error in any of the commands. 
Programs which execute under CP/M can abort processing of 
command files when error conditions occur by simply erasing 
any existing $$$.SUB file. 

In order to introduce dollar signs into a SUBMIT file, the user may 
type a "$$" which reduces to a single "$" within the command 
file Further an up-arrow symbol "T" may precede an alphabetic 
character x, which produces a single ctl-x character within the 
file. 

The last command in a SUB file can initiate another SUB file, thus 
allowing chained batch commands. 

Suppose the file ASMBL.SUB exists on disk and contains the 
prototype commands 



ASM $1 

DIR $1* 

ERA *.BAK 

PIP $2 = $1 .PRN 

ERA $1.PRN 



and the command 

SUBMIT ASMBLX PRN <cr> 

is issued by the operator. The SUBMIT program reads the 
ASMBL SUB file substituting "X" for all occurrences of $1 and 
"PRN" for all occurrences of $2, resulting in a $$$.SUB file 
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containing the commands 

ASM X 

DIR X.* 

ERA *.BAK 

PIP PRN: = X.PRN 

ERA X.PRN 

which are executed in sequence by the CCP. 

The SUBMIT function can access a SUB file which is on an alternate 
drive by preceding the file name by a drive name. Submitted 
files are only acted upon, however, when they appear on drive A. 
Thus, it is possible to create a submitted file on drive B which is 
executed at a later time when it is inserted in drive A. 

XSUB 

XSUB extends the power of the SUBMIT facility to include character 
input during program execution as well as entering command 
lines. The XSUB command is included as the first line of your 
submit file and, when executed, self-relocates directly below the 
CCP. 

All subsequent submit command lines are processed by XSUB, so 
that programs which read buffered console input (BDOS function 
10) receive their input directly from the submit file. For example, 
the file SAVER. SUB could contain the submit lines: 

XSUB 
DDT 
l$1.HEX 
R 

GO 

SAVE 1 $2.COM 
with a subsequent SUBMIT command: 

SUBMIT SAVER X Y 
which substitutes X for $1 and Y for $2 in the command stream. 
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The XSUB program loads, followed by DDT which is sent the 
command lines "IX.HEX" "R" and "GO," thus returning to the CCP. 
The final command "SAVE 1 Y.COM" is processed by the CCP. 

The XSUB program remains in memory, and prints the message 

(xsub active) 

on each warm start operation to indicate its presence. Subsequent 
submit command streams do not require the XSUB, unless an 
intervening cold start has occurred. Note that XSUB must be 
loaded after DESPOOL, if both are to run simultaneously. 

DUMP 

The DUMP program types the contents of the disk file (ufn) at the 
console in hexadecimal form. The file contents are listed sixteen 
bytes at a time, with the absolute byte address listed to the left of 
each line in hexadecimal. Long typeouts can be aborted by 
pushing the rubout key during printout. (The source listing of the 
DUMP program is given in the "CP/M Interface Guide" as an 
example of a program written for the CP/M environment.) 

BDOS Error Messages 



There are three error situations which the Basic Disk Operating 
System intercepts during file processing. When one of these 
conditions is detected, the BDOS prints the message: 

BDOS ERR ON x: error 

where x is the drive name, and "error" is one of the three error 
messages: 

BAD SECTOR 
SELECT 

R/O 

The "BAD SECTOR" message indicates that the disk controller 
electronics has detected an error condition in reading or writing 
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the diskette. This condition is generally due to a malfunctioning 
disk controller, or an extremely worn diskette. If you find that 
your system reports this error more than once a month, you should 
check the state of your controller electronics, and the condition 
of your media. In any case, recovery from this condition is 
accomplished by typing a ctl-C to reboot (this is the safest!), or a 
return, which simply ignores the bad sector in the file operation. 
Note, however, that typing a return may destroy your diskette 
integrity if the operation is a directory write, so make sure you 
have adequate backups in this case. 

The "SELECT" error occurs when there is an attempt to address a 
drive beyond the A through D range. In this case, the value of x in 
the error message gives the selected drive. The system reboots 
following any input from the console. 

The R/O (read only) message occurs when there is an attempt to 
write to a diskette which has been designated as read-only in a 
STAT command, or has been set to read-only by the BDOS. In 
general, the operator should reboot CP/M either by using the 
warm start procedure ctl-C or by performing a cold start whenever 
the diskettes are changed. If a changed diskette is to be read but 
not written, BDOS allows the diskette to be changed without the 
warm or cold start, but internally marks the drive as read-only. 
The status of the drive is subsequently changed to read/write for 
input from the console. An automatic warm start takes place 
following any input. 
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2 

CP/M 2.0 Interface Guide 



Introduction 



This manual describes CP/M, release 2, system organization 
including the structure of memory and system entry points. The 
intention is to provide the necessary information required to write 
programs which operate under CP/M, and which use the peripheral 
and disk I/O facilities of the system. 

CP/M is logically divided into four parts, called the Basic I/O 
System (BIOS), the Basic Disk Operating System (BDOS), the 
Console command processor (CCP), and the Transient Program 
Area (TPA). The BIOS is a hardware-dependent module which 
defines the exact low level interface to a particular computer 
system which is necessary for peripheral device I/O. The BIOS and 
BDOS are logically combined into a single module with a common 
entry point, and referred to as the FDOS. The CCP is a distinct 
program which uses the FDOS to provide a human-oriented 
interface to the information which is cataloged on the backup 
storage device. The TPA is an area of memory (i.e., the portion 
which is not used by the FDOS and CCP) where various non- 
resistant operating system commands and user programs are 
executed. The lower portion of memory is reserved for system 
information and is detailed in later sections. 
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Memory organization of the CP/M system is shown below: 



high memory 
FBASE: 
CBASE: 

TBASE: 
BOOT: 



FDOS (BDOS + BIOS) 



CCP 



TPA 



system parameters 



Base addresses for the two Apple memory configurations that 
can be used with CP/M are shown in the table below: 



Module 


44 K 


56K (Language Card) 


CCP 


9400 H 


C400H 


BDOS 


9C00H 


CC00H 


BIOS 


AA00H 


DA00H 


Top of RAM 


AFFFH 


DFFFH 



All standard CP/M versions assume BOOT=0000H, which is the 
base of random access memory. The machine code found at 
location BOOT performs a system "warm start" which loads and 
initializes the programs and variables necessary to return control 
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to the CCP. Thus, transient programs need only jump to location 
BOOT to return control to CP/M at the command level. Further, 
the standard versions assume TBASE=BOOT+01 00H which is 
normally location 0100H. The principal entry point to the FDOS 
is at location BOOT+0005H (normally 0005H) where a jump to 
FBASE is found. The address field at BOOT+0006H (normally 
0006H) contains the value of FBASE and can be used to determine 
the size of available memory, assuming the CCP is being 
overlayed by a transient program. 

Transient programs are loaded into the TPA and executed as 
follows. The operator communicates with the CCP by typing 
command lines following each prompt. Each command line takes 
one of the forms: 

command 
command filel 
command filel file2 

where "command" is either a built-in function such as DIR or 
TYPE, or the name of a transient command or program. If the 
command is a built-in function of CP/M, it is executed immediately. 
Otherwise, the CCP searches the currently addressed disk for a 
file by the name 

command.COM 

If the file is found, it is assumed to be a memory image of a 
program which executes in the TPA, and thus implicitly originates 
at TBASE in memory. The CCP loads the COM file from the disk 
into memory starting at TBASE and possibly extending up to 
CBASE. 

If the command is followed by one or two file specifications, the 
CCP prepares one or two file control block (FCB) names in the 
system parameter area. These optional FCB's are in the form 
necessary to access files through the FDOS, and are described 
in the next section. 
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The transient program receives control from the CCP and begins 
execution, perhaps using the I/O facilities of the FDOS. The 
transient program is "called" from the CCP, and thus can simply 
return to the CCP upon completion of its processing, or can jump 
to BOOT to pass control back to CP/M. In the first case, the 
transient program must not use memory above CBASE, while in 
the latter case, memory up through FBASE-1 is free. 

The transient program may use the CP/M I/O facilities to 
communicate with the operator's console and peripheral devices, 
including the disk subsystem. The I/O system is accessed by 
passing a "function number" and an "information address" to CP/M 
through the FDOS entry point at BOOT+005H. In the case of a 
disk read, for example, the transient program sends the number 
corresponding to a disk read, along with the address of an FCB 
to the CP/M FDOS. The FDOS, in turn, performs the operation and 
returns with either a disk read completion indication or an error 
number indicating that the disk read was unsuccessful. The function 
numbers and error indicators are given below. 
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Operating System Call Conventions 



The purpose of this section is to provide detailed information for 
performing direct operating system calls from user programs. 

CP/M facilities which are available for access by transient 
programs fall into two general categories: simple device I/O, and 
disk file I/O. The simple device operations include: 

Read a Console Character 
Write a Console Character 
Read a Sequential Tape Character 
Write a Sequential Tape Character 
Write a List Device Character 
Get or Set I/O Status 
Print Console Buffer 
Read Console Buffer 
Interrogate Console Ready 

The FDOS operations which perform disk Input/Output are 

Disk System Reset 
Drive Selection 
File Creation 
File Open 
File Close 
Directory Search 
File Delete 
File Rename 

Random or Sequential Read 
Random or Sequential Write 
Interrogate Available Disks 
Interrogate Selected Disk 
Set DMA Address 
Set/Reset File Indicators 

As mentioned above, access to the FDOS functions is accomplished 
by passing a function number and information address through 
the primary entry point at location BOOT+0005H. In general, the 
function number is passed in register C with the information 
address in the double byte pair DE. Single byte values are returned 
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in register A, with double byte values returned in HL (a zero 
value is returned when the function number is out of range). For 
reasons of compatibility, register A=L and register B=H upon 
return in all cases. The CP/M function numbers are: 



o 


System Reset 


19 


Delete File 


1 


Console Input 


20 


Read Sequential 


2 


Console OutDut 


21 


Write Sequential 


3 


Reader Input 


22 


Make File 


4 


Punch Output 


23 


Rename File 


5 


List Output 


24 


Return Login Vector 


6 


Dirpct Console I/O 


25 


Return Current Disk 


7 


Get I/O Byte 


26 


Set DMA Address 


8 


Set I/O Byte 


27 


Get Addr (Alloc) 


9 


Print String 


28 


Write Protect Disk 


10 


Read Console Buffer 


29 


Get R/O Vector 


11 


Get Console Status 


30 


Set File Attributes 


12 


Return Version Number 


31 


Get Addr (Disk Parms 


13 


Reset Disk System 


32 


Set/Get User Code 


14 


Select Disk 


33 


Read Random 


15 


Open File 


34 


Write Random 


16 


Close File 


35 


Compute File Size 


17 


Search for First 


36 


Set Random Record 


18 


Search for Next 







(Functions 28 and 32 should be avoided in application programs to 
maintain upward compatibility with MP/M.) 

Upon entry to a transient program, the CCP leaves the stack 
pointer set to an eight level stack area with the CCP return address 
pushed onto the stack, leaving seven levels before overflow 
occurs. Although this stack is usually not used by a transient 
program (i.e., most transients return to the CCP through a jump 
to location 0000H), it is sufficiently large to make CP/M system 
calls since the FDOS switches to a local stack at system entry. 
The following assembly language program segment, for example, 
reads characters continuously until an asterisk is encountered, at 
which time control returns to the CCP (assuming a standard CP/M 
system with BOOT+0000H): 
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BDOS 


EQU 


0005 H 


;STANDARD CP/M ENTRY 


CONIN 


EQU 


1 


CONSOLE INPUT FUNCTION 




ORG 


0100H 


BASE OF TPA 


NEXTC: 


MVI 


CCONIN 


READ NEXT CHARACTER 




CALL 


BDOS 


RETURN CHARACTER IN <A> 




CPI 




END OF PROCESSING? 




JNZ 


NEXTC 


LOOP IF NOT 




RET 




RETURN TO CCP 




END 







CP/M implements a named file structure on each disk, providing a 
logical organization which allows any particular file to contain 
any number of records from completely empty to the full capacity 
of the drive. Each drive is logically distinct with a disk directory 
and file data area. The disk file names are in three parts: the drive 
select code, the file name consisting of one to eight non-blank 
characters, and the file type consisting of zero to three non-blank 
characters. The file type names the generic category or a 
particular file, while the file name distinguishes individual files in 
each category. The file types listed below name a few generic 
categories which have been established, although they are generally 
arbitrary: 



ASM 


Assembler Source 


PLI 


PL/I Source File 


PRN 


Printer Listing 


REL 


Relocatable Module 


HEX 


Hex Machine Code 


TEX 


TEX Formatter Source 


BAS 


Basic Source File 


BAK 


ED Source Backup 


INT 


Intermediate Code 


SYM 


SID Symbol File 


COM 


CCP Command File 


$$$ 


Temporary File 



Source files are treated as a sequence of ASCII characters, where 
each "line" of the source file is followed by a carriage-return 
line-feed sequence (ODH followed by OAH). Thus one 128 byte 
CP/M record could contain several lines of source text. The end 
of an ASCII file is denoted by a control-Z character (1 AH) or a real 
end of file, returned by the CP/M read operation. Control-Z 
characters embedded within machine code files (e.g., COM files) 
are ignored, however, and the end of file condition returned by 
CP/M is used to terminate read operations. 
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Files in CP/M can be thought of as a sequence of up to 65536 
records of 128 bytes each, numbered from through 65535, 
thus allowing a maximum of 8 megabytes per file. Note, however, 
that although the records may be considered logically contiguous, 
they may not be physically contiguous in the disk data area. 
Internally, all files are broken into 16K byte segments called 
logical extents, so that counters are easily maintained as 8-bit 
values. Although the decomposition into extents is discussed in 
the paragraphs which follow, they are of no particular consequence 
to the programmer since each extent is automatically accessed 
in both sequential and random access modes. 

In the file operations starting with function number 15, DE usually 
addresses a file control block (FCB). Transient programs often 
use the default file control block area reserved by CP/M at location 
BOOT+005CH (normally 005CH) for simple file operations. The 
basic unit of file information is a 128 byte record used for all file 
operations, thus a default location for disk I/O is provided by 
CP/M at location BOOT+0080H (normally 0080H) which is the 
initial default DMA address (see function 26). All directory 
operations take place in a reserved area which does not affect 
write buffers as was the case in release 1 , with the exception of 
Search for First and Search for Next, where compatibility 
is required. 

The File Control Block (FCB) data area consists of a sequence of 
33 bytes for sequential access and a series of 36 bytes in the 
case that the file is accessed randomly. The default file control 
block normally located at 005CH can be used for random access 
files, since the three bytes starting at BOOT+007DH are available 
for this purpose. The FCB format is shown with the following fields: 



dr 


f1 


f2 


/ / 


f8 


t1 


t2 


t3 


ex 


s1 


s2 


rc 


dO 


/ / 


dn 


cr 


rO 


r1 


r2 



00 01 02 ... 08 09 10 11 12 13 14 15 16 . . . 31 32 33 34 35 
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where 



dr drive code (0 - 16) 

0=>use default drive for file 
1=>auto disk select drive A, 
2=>auto disk select drive B, 

1 6=>auto disk select drive P. 

f1 . . . f8 contain the file name in ASCII upper case, 

with high bit=o 

t1, t2, t3 contain the file type in ASCII upper case, 
with high bit=0 

t1 ',t2', and t3' denote the bit of these 
positions, 

t1'=1=> Read/Only file, 
t2'=1=>SYS file.no DIR list 

ex contains the current extent number, 

normally set to 00 by the user, but in range 
0-31 during file I/O 

s1 reserved for internal system use 

s2 reserved for internal system use, set to zero 

on call to OPEN, MAKE, SEARCH 

rc record count for extent "ex," takes on values 

from - 1 28 

dO . . . dn filled-in by CP/M, reserved for system use 

cr current record to read or write in a 

sequential file operation, normally set to 
zero by user 

rO, r1, r2 optional random record number in the range 
0-65535, with overflow to r2, rO, r1 constitute 
a 16-bit value with low byte rO, and high 
byte r 1 
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Each file being accessed through CP/M must have a corresponding 
FCB which provides the name and allocation information for all 
subsequent file operations. When accessing files, it is the 
programmer's responsibility to fill the lower sixteen bytes of the 
FCB and initialize the "cr" field. Normally, bytes 1 through 1 1 are 
set to the ASCII character values for the file name and file type, 
while all other fields are zero. 

FCB's are stored in a directory area of the disk, and are brought 
into central memory before proceeding with file operations (see 
the OPEN and MAKE functions). The memory copy of the FCB is 
updated as file operations take place and later recorded permanently 
on disk at the termination of the file operation (see the CLOSE 
command). 

The CCP constructs the first sixteen bytes of two optional FCB's for 
a transient by scanning the remainder of the line following the 
transient name, denoted by "filel " and "file2" in the prototype 
command line described above, with unspecified fields set to 
ASCII blanks. The first FCB is constructed at location BOOT+005CH, 
and can be used as-is for subsequent file operations. The second 
FCB occupies the d) . . . dn portion of the first FCB, and must be 
moved to another area of memory before use. If, for example, 
the operator types 

PROGNAME B:X.ZOT Y.ZAP 

the file PROGNAME. COM is loaded into the TPA, and the default 
FCB at BOOT+005CH is initialized to drive code 2, file name "X" 
and file type "ZOT." The second drive code takes the default value 
0, which is placed at BOOT+006CH, with the file name "Y" 
placed into location BOOT+006DH and file type "ZAP" located 8 
bytes later at BOOT+0075H. All remaining fields through "cr" 
are set to zero. Note again that it is the programmer's responsibility 
to move this second file name and type to another area, usually a 
separate file control block, before opening the file which begins at 
BOOT+005CH, due to the fact that the open operation will 
overwrite the second name and type. 

If no file names are specified in the original command, then the 
fields beginning at BOOT+005DH and BOOT+006DH contain 



56 CP/M Reference Manual 



blanks. In all cases, the CCP translates lower case alphabetics to 
upper case to be consistent with the CP/M file naming 
conventions. 

As an added convenience, the default buffer area at location 
BOOT+0080H is initialized to the command line tail typed by the 
operator following the program name. The first position contains 
the number of characters, with the characters themselves following 
the character count. Given the above command line, the area 
beginning at BOOT+0080H is initialized as follows: 

BOOT+0080H: 

+00+01 +02 +03 +04+05 +06 +07 +08 +09+10+11 +12+13+14 
14 B" ":" "X" "." "Z" "O" "T Y" "." "Z" "A" "P" 

where the characters are translated to upper case ASCII with 
uninitialized memory following the last valid character. Again, it 
is the responsibility of the programmer to extract the information 
from this buffer before any file operations are performed, unless 
the default DMA address is explicitly changed. 

The individual functions are described in detail in the pages which 
follow. 

Function 0: System Reset 

Entry Parameters: 

Register C: 00H 

The system reset function returns control to the CP/M operating 
system at the CCP level. The CCP re-initializes the disk subsystem 
by selecting and logging-in disk drive A. This function has exactly 
the same effect as a jump to location BOOT. 
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Function 1: Console Input 

Entry Parameters: 

Register C: 01 H 

Returned Value: 

Register A: ASCII Character 

The console input function reads the next console character to 
register A. Graphic characters, along with carriage return, line 
feed, and backspace (ctl-H) are echoed to the console. Tab 
characters (ctl-l) are expanded in columns of eight characters. A 
check is made for start/stop scroll (ctl-S) and start/stop printer 
echo (ctl-P). The FDOS does not return to the calling program 
until a character has been typed, thus suspending execution of a 
character if not ready. 

Function 2: Console Output 

Entry Parameters: 

Register C: 02H 

Register E: ASCII Character 

The ASCII character from register E is sent to the console 
device. Similar to function 1 , tabs are expanded and checks are 
made for start/stop scroll and printer echo. 

Function 3: Reader Input 

Entry Parameters: 

Register C: 03H 

Returned Value: 

Register A: ASCII Character 

The Reader Input function reads the next character from the 
logical reader into register A. Control does not return until the 
character has been read. 
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Function 4: Punch Output 

Entry Parameters: 

Register C: 04H 

Register E: ASCII Character 

The Punch Output function sends the character from register E to 
the logical punch device. 

Function 5: List Output 

Entry Parameters: 

Register C: 05H 

Register E: ASCII Character 

The List Output function sends the ASCII character in register E to 
the logical listing device. 

Function 6: Direct Console I/O 

Entry Parameters: 

Register C: 06H 
Register E: OFFH (input) or 
char (output) 

Returned Value: 

Register A: char or status 
(no value) 

Direct console I/O is supported under CP/M for those specialized 
applications where unadorned console input and output is 
required. Use of this function should, in general, be avoided since 
it bypasses all of CP/M's normal control character functions (e.g., 
control-S and control-P). Programs which perform direct I/O through 
the BIOS under previous releases of CP/M, however, should be 
changed to use direct I/O under BDOS so that they can be fully 
supported under future releases of MP/M and CP/M. 
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Upon entry to function 6, register E either contains hexadecimal 
FF, denoting a console input request, or register E contains an 
ASCII character. If the input value is FF, then function 6 returns 
A=00 if no character is ready, otherwise A contains the next 
console input character. 

If the input value in E is not FF, then function 6 assumes that E 
contains a valid ASCII character which is sent to the console. 

Function 7: Get I/O Byte 

Entry Parameters: 

Register C: 07H 

Returned Value: 

Register A: I/O Byte Value 

The Get I/O Byte function returns the current value of IOBYTE in 
register A. 

Function 8: Set I/O Byte 

Entry Parameters: 

Register C: 08H 

Register E: I/O Byte Value 

The Set I/O Byte function changes the system IOBYTE value to 
that given in register E. 

Function 9: Print String 

Entry Parameters: 

Register C: 09H 
Registers DE: String Address 

The Print String function sends the character string stored in 
memory at the location given by DE to the console device, until a 
"$" is encountered in the string. Tabs are expanded as in function 
2, and checks are made for start/stop scroll and printer echo. 
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Function 10: Read Console Buffer 

Entry Parameters: 

Register C: OAH 
Registers DE: Buffer Address 

Returned Value: 

Console Characters in Buffer 

The Read Buffer function reads a line of edited console input 
into a buffer addressed by registers DE. Console input is terminated 
when either the input buffer overflows. The Read Buffer takes 
the form: 



DE: +0 +1 +2 +3 +4 +5 +6 +7 +£ 



+ n 



mx 


nc 


d 


c2 


c3 


c4 


c5 


c6 


C7 




?? 



where "mx" is the maximum number of characters which the buffer 
will hold (1 to 255), "nc" is the number of characters read (set by 
FDOS upon return), followed by the characters read from the 
console. If nc < mx, then uninitialized positions follow the last 
character, denoted by "??" in the above figure. A number of control 
functions are recognized during line editing: 



rub/del removes and echoes the last character 

ctl-C reboots when at the beginning of line 

ctl-E causes physical end of line 

ctl-H backspaces one character position 

ctl-J (line feed) terminates input line 

ctl-M (return) terminates input line 

ctl-R retypes the current line after new line 

ctl-X backspaces to beginning of current line 



Note also that certain functions which return the carriage to the 
leftmost position (e.g., ctl-X) do so only to the column position 
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where the prompt ended (in earlier releases, the carriage returned 
to the extreme left margin). This convention makes operator data 
input and line correction more legible. 

Function 1 1: Get Console Status 

Entry Parameters: 

Register C: OBH 

Return Value: 

Register A: Console Status 

The Console Status function checks to see if a character has been 
typed at the console. If a character is ready, the value OFFH is 
returned in register A. Otherwise a 00H value is returned. 

Function 12: Return Version Number 

Entry Parameters: 

Register C: OCH 

Returned Value: 

Registers HL: Version Number 

Function 12 provides information which allows version independent 
programming. A two-byte value is returned, with FNOO designating 
the CP/M release (H=01 for MP/M), and L=00 for all releases 
previous to 2.0. CP/M 2.0 returns a hexadecimal 20 in register L, 
with subsequent version 2 releases in the hexadecimal range 21 , 
22, through 2F. Using function 12, for example, you can write 
application programs which provide both sequential and random 
access functions, with random access disabled when operating 
under early releases of CP/M. 
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Function 13: Reset Disk System 

Entry Parameters: 

Register C: ODH 

The Reset Disk function is used to programmatically restore the 
file system to a reset state where all disks are set to read/write 
(see functions 28 and 29), only disk drive A is selected, and the 
default DMA address is reset to BOOT+0080H. This function can 
be used, for example, by an application program which requires a 
disk change without a system reboot. 

Function 14: Select Disk 

Entry Parameters: 

Register C: OEH 
Register E: Selected Disk 

The Select Disk function designates the disk drive named in 
register E as the default disk for subsequent file operations, with 
E=0 for drive A, 1 for drive B, and so-forth through 15 corresponding 
to drive P in a full sixteen drive system. The drive is placed in an 
"on-line" status which, in particular, activates its directory until the 
next cold start, warm start, or disk system reset operation. If the 
disk media is changed while it is on-line, the drive automatically 
goes to a read/only status in a standard CP/M environment (see 
function 28). FCB's which specify drive code zero (dr=OOH) 
automatically reference the currently selected default drive. 
Drive code values between 1 and 16, however, ignore the selected 
default drive and directly reference drives A through P. 
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Function 15: Open File 

Entry Parameters: 

Register C: OFH 
Registers DE: FCB Address 

Returned Value: 

Register A: Directory Code 

The Open File operation is used to activate a file which currently 
exists in the disk directory for the currently active user number. 
The FDOS scans the referenced disk directory for a match in 
positions 1 through 14 of the FCB referenced by DE (byte s1 is 
automatically zeroed), where an ASCII question mark (3FH) 
matches any directory character in any of these positions. 
Normally, no question marks are included and, further, bytes "ex" 
and "s2" of the FCB are zero. 

If a directory element is matched, the relevant directory information 
is copied into bytes dO through dn of the FCB, thus allowing 
access to the files through subsequent read and write operations. 
Note that an existing file must not be accessed until a successful 
open operation is completed. Upon return, the open function 
returns a "directory code" with the value through 3 if the open 
was successful, or OFFH (255 decimal) if the file cannot be found. 
If question marks occur in the FCB then the first matching FCB 
is activated. Note that the current record ("cr") must be zeroed by 
the program if the file is to be accessed sequentially from the 
first record. 
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Function 16: Close File 

Entry Parameters: 

Register C: 10H 
Registers DE: FCB Address 

Returned Value: 

Register A: Directory Code 

The Close File function performs the inverse of the open file 
function. Given that the FCB addressed by DE has been previously 
activated through an open or make function (see functions 15 
and 22), the close function permanently records the new FCB in 
the referenced disk directory. The FCB matching process for the 
close is identical to the open function. The directory code returned 
for a successful close operation is 0, 1 , 2, or 3, while a OFFH 
(255 decimal) is returned if the file name cannot be found in the 
directory. A file need not be closed if only read operations have 
taken place. If write operations have occurred, however, the close 
operation is necessary to permanently record the new directory 
information. 

Function 17: Search for First 

Entry Parameters: 

Register C: 11H 
Registers DE: FCB Address 

Returned Value: 

Register A: Directory Code 

Search for First scans the directory for a match with the file given 
by the FCB addressed by DE. The value 255 (hexadecimal FF) is 
returned if the file is not found, otherwise 0, 1 , 2, or 3 is returned 
indicating the file is present. In the case that the file is found, the 
current DMA address is filled with the record containing the 
directory entry, and the relative starting position is A *32 (i.e., 
rotate the A register left 5 bits, or ADD A five times). Although 
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not normally required for application programs, the directory 
information can be extracted from the buffer at this position. 

An ASCII question mark (63 decimal, 3F hexadecimal) in any 
position from "f1 " through "ex" matches the corresponding field of 
any directory entry on the default or auto-selected disk drive. If 
the "dr" field contains an ASCII question mark, then the auto disk 
selected function is disabled, the default disk is searched, with 
the search function returning any matched entry, allocated or free, 
belonging to any user number. This latter function is not normally 
used by application programs, but does allow complete flexibility to 
scan all current directory values. If the "dr" field is not a question 
mark, the "s2" byte is automatically zeroed. 

Function 18: Search for Next 

Entry Parameters: 

Register C: 12H 

Returned Value: 

Register A: Directory Code 

The Search for Next function is similar to the Search for First 
function, except that the directory scan continues from the last 
matched entry. Similar to function 17, function 18 returns the decimal 
value 255 in A when no more directory items match. 

Function 19: Delete File 

Entry Parameters: 

Register C: 13H 
Registers DE: FCB Address 

Returned Value: 

Register A: Directory Code 

The Delete File function removes files which match the FCB 
addresses by DE. The filename and type may contain ambiguous 
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references (i.e., question marks in various positions), but the drive 
select code cannot be ambiguous, as in the Search and Search for 
Next functions. 

Function 1 9 returns a decimal 255 if the referenced file or files 
cannot be found, otherwise a value in the range to 3 is 
returned. 

Function 20: Read Sequential 

Entry Parameters: 

Register C: 14H 
Registers DE: FCB Address 

Returned Value: 

Register A: Directory Code 

Given that the FCB addressed by DE has been activated through 
an open or make function (numbers 15 and 22), the Read Sequential 
function reads the next 128 byte record from the file into memory 
at the current DMA address. The record is read from position "cr" 
of the extent, and the "cr" field is automatically incremented to 
the next record position. If the "cr" field overflows then the next 
logical extent is automatically opened and the "cr" field is reset 
to zero in preparation for the next read operation. The value 00H is 
returned in the A register if the read operation was successful, 
while a non-zero value is returned if no data exists at the next 
record position (e.g., end of file occurs). 

Function 21: Write Sequential 

Entry Parameters: 

Register C: 15H 
Registers DE: FCB Address 

Returned Value: 



Register 



A: Directory Code 
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Given that the FCB addressed by DE has been activated through 
an open or make function (numbers 15 and 22), the Write 
Sequential function writes the 128 byte data record at the current 
DMA address to the file named by the FCB. The record is placed 
at position "cr" of the file, and the "cr" field is automatically 
incremented to the next record position. If the "cr" field overflows 
then the next logical extent is automatically opened and the "cr" 
field is reset to zero in preparation for the next write operation. 
Write operations can take place into an existing file, in which case 
newly written records overlay those which already exist in the 
file. Register A=00H upon return from a successful write operation, 
while a non-zero value indicates an unsuccessful write due to a 
full disk. 

Function 22: Make File 

Entry Parameters: 

Register C: 16H 
Registers DE: FCB Address 

Returned Value: 

Register A: Directory Code 

The Make File operation is similar to the open file operation 
except that the FCB must name a file which does not exist in the 
currently referenced disk directory (i.e., the one named explicitly 
by a non-zero "dr" code, or the default disk if "dr" is zero). The 
FDOS creates the file and initializes both the directory and main 
memory value to an empty file. The programmer must ensure that 
no duplicate file names occur, and a preceding delete operation 
is sufficient if there is any possibility of duplication. Upon return, 
register A=0, 1 , 2, or 3 if the operation was successful and OFFH 
(255 decimal) if no more directory space is available. The make 
function has the side-effect of activating the FCB and thus a 
subsequent open is not necessary. 
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Function 23: Rename File 

Entry Parameters: 

Register C: 17H 
Registers DE: FCB Address 

Returned Value: 

Register A: Directory Code 

The Rename function uses the FCB addressed by DE to change 
all occurrences of the file named in the first 16 bytes to the file 
named in the second 16 bytes. The drive code "dr" at position 
is used to select the drive, while the drive code for the new file 
name at position 16 of the FCB is assumed to be zero. Upon 
return, register A is set to a value between and 3 if the rename 
was successful, and OFFH (255 decimal) if the first file name 
could not be found in the directory scan. 

Function 24: Return Login Vector 

Entry Parameters: 

Register C: 18H 

Returned Value: 

Registers HL: Login Vector 

The login vector value returned by CP/M is a 16-bit value in HL, 
where the least significant bit of L corresponds to the first drive 
A, and the high order bit of H corresponds to the sixteenth drive, 
labelled PA "0" bit indicates that the drive is not on-line, while a 
"1 " bit marks a drive that is actively on-line due to an explicit disk 
drive selection, or an implicit drive select caused by a file 
operation which specified a non-zero "dr" field. Note that 
compatibility is maintained with earlier releases, since registers A 
and L contain the same values upon return. 
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Function 25: Return Current Disk 

Entry Parameters: 

Register C: 19H 

Returned Value: 

Register A: Current Disk 

Function 25 returns the currently selected default disk number 
in register A. The disk numbers range from through 1 5 
corresponding to drives A through P. 

Function 26: Set DMA Address 

Entry Parameters: 

Regular C: 1 AH 
Registers DE: DMA Address 

"DMA" is an acronym for Direct Memory Address, which is often 
used in connection with disk controllers which directly access the 
memory of the mainframe computer to transfer data to and from 
the disk subsystem. Although many computer systems use non-DMA 
access (i.e., the data is transferred through programmed I/O 
operations), the DMA address has, in CP/M, come to mean the 
address at which the 128 byte data record resides before a disk 
write and after a disk read. Upon cold start, warm start, or disk 
system reset, the DMA address is automatically set to 
BOOT+0080H. The Set DMA function, however, can be used to 
change this default value to address another area of memory where 
the data records reside. Thus, the DMA address becomes the 
value specified by DE until it is changed by a subsequent Set DMA 
function, cold start, warm start, or disk system reset. 
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Function 27: Get ADDR (ALLOC) 

Entry Parameters: 

Register C: 1BH 

Returned Value: 

Registers HL: ALLOC Address 

An "allocation vector" is maintained in main memory for each 
on-line disk drive. Various system programs use the information 
provided by the allocation vector to determine the amount of 
remaining storage (see the STAT program). Function 27 returns the 
base address of the allocation vector for the currently selected 
disk drive. The allocation information may, however, be invalid if 
the selected disk has been marked read/only. Although this 
function is not normally used by application programs, additional 
details of the allocation vector are found in the "CP/M Alteration 
Guide." 

Function 28: Write Protect Disk 

Entry Parameters: 

Register C: 1CH 

The disk write protect function provides temporary write protection 
for the currently selected disk. Any attempt to write to the disk, 
before the next cold or warm start operation produces the message 

Bdos Err on d: R/O 
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Function 29: Get Read/Only Vector 

Entry Parameters: 

Register C: 1DH 

Returned Value: 

Registers HL: R/O Vector Value 

Function 29 returns a bit vector in register pair HL which indicates 
drives which have the temporary read/only bit set. Similar to 
function 24, the least significant bit corresponds to drive A, while 
the most significant bit corresponds to drive P. The R/O bit is set 
either by the explicit call to function 28, or by the automatic 
software mechanisms within CP/M which detect changed disks. 

Function 30: Set File Attributes 

Entry Parameters: 

Register C: 1 EH 
Registers DE: FCB Address 

Returned Value: 

Register A: Directory Code 

The Set File Attributes function allows programmatic manipulation 
of permanent indicators attached to files. In particular, the R/O 
and System attributes (t1 ' and t2') can be set or reset. The DE pair 
addresses an unambiguous file name with the appropriate 
attributes set or reset. Function 30 searches for a match, and 
changes the matched directory entry to contain the selected 
indicators. Indicators f 1 ' through f4' are not presently used, but 
may be useful for applications programs, since they are not 
involved in the matching process during file open and close 
operations. Indicators f5' through f8' and t3' are reserved for 
future system expansion. 
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Function 3 1: Get ADDR (Disk PA RMS) 

Entry Parameters: 

Register C: 1FH 

Returned Value: 

Registers HL: DPB Address 

The address of the BIOS resident disk parameter block is returned 
in HL as a result of this function call. This address can be used 
for either of two purposes. First, the disk parameter values can be 
extracted for display and space computation purposes, or transient 
programs can dynamically change the values of current disk 
parameters when the disk environment changes, if required. 
Normally, application programs will not require this facility. 

Function 32: Set/Get User Code 



Entry Parameters: 

Register C: 20H 
Register E: OFFH (get) or 
User Code (set) 

Returned Value: 

Register A: Current Code or 
(no value) 

An application program can change or interrogate the currently 
active user number by calling function 32. If register E=0FFH, then 
the value of the current user number is returned in register A, 
where the value is in the range to 31 . If register E is not OFFH, 
then the current user number is changed to the value of E 
(modulo 32). 
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Function 33: Read Random 

Entry Parameters: 

Register C: 21 H 
Registers DE: FCB Address 

Returned Value: 

Register A: Return Code 

The Read Random function is similar to the sequential file read 
operation of previous releases, except that the read operation 
takes place at a particular record number, selected by the 24-bit 
value constructed from the three byte field following the FCB (byte 
positions rO at 33, r1 at 34, and r2 at 35). Note that the sequence 
of 24 bits is stored with least significant byte first (rO), middle byte 
next (r1 ), and high byte last (r2). CP/M does not reference byte 
r2, except in computing the size of a file (function 35). Byte r2 must 
be zero, however, since a non-zero value indicates overflow past 
the end of file. 

Thus, the r0,r1 byte pair is treated as a double-byte, or "word" 
value, which contains the record to read. This value ranges from 
to 65535, providing access to any particular record of the 8 
megabyte file. In order to process a file using random access, 
the base extent (extent 0) must first be opened. Although the base 
extent may or may not contain any allocated data, this ensures 
that the file is properly recorded in the directory, and is visible in 
DIR requests. The selected record number is then stored into 
the random record field (r0,r1 ), and the BDOS is called to read the 
record. Upon return from the call, register A either contains an 
error code, as listed below, or the value 00 indicating the operation 
was successful. In the latter case, the current DMA address 
contains the randomly accessed record. Note that contrary to the 
sequential read operation, the record number is not advanced. 
Thus, subsequent random read operations continue to read the 
same record. 
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Upon each random read operation, the logical extent and current 
record values are automatically set. Thus, the file can be sequentially 
read or written, starting from the current randomly accessed 
position. Note, however, that in this case, the last randomly read 
record will be re-read as you switch from random mode to 
sequential read, and the last record will be re-written as you switch 
to a sequential write operation. You can, of course, simply 
advance the random record position following each random read or 
write to obtain the effect of a sequential I/O operation. 

Error codes returned in Register A following a random read are 
listed below. 

01 reading unwritten data 

02 (not returning in random mode) 

03 cannot close current extent 

04 seek to unwritten extent 

05 (not returned in read mode) 

06 seek past physical end of disk 

Error code 01 and 04 occur when a random read operation accesses 
a data block which has not been previously written, or an extent 
which has not been created, which are equivalent conditions. Error 
3 does not normally occur under proper system operation, but 
can be cleared by simply re-reading, or re-opening extent zero as 
long as the disk is not physically write protected. Error code 06 
occurs whenever byte r2 is non-zero under the current 2.0 release. 
Normally, non-zero return codes can be treated as missing data, 
with zero return codes indicating operation complete. 
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Function 34: Write Random 

Entry Parameters: 

Register C: 22H 
Registers DE: FCB Address 

Returned Value: 

Register A: Return Code 

The Write Random operation is initiated similar to the Read 
Random call, except that data is written to the disk from the current 
DMA address. Further, if the disk extent or data block which is 
the target of the write has not yet been allocated, the allocation is 
performed before the write operation continues. As in the Read 
Random operation, the random record number is not changed as a 
result of the write. The logical extent number and current record 
positions of the file control block are set to correspond to the 
random record which is being written. Again, sequential read or 
write operations can commence following a random write, with the 
notation that the currently addressed record is either read or 
rewritten again as the sequential operation begins. You can also 
simply advance the random record position following each write 
to get the effect of a sequential write operation. Note that in 
particular, reading or writing the last record of an extent in 
random mode does not cause an automatic extent switch as it does 
in sequential mode. 

The error codes returned by a random write are identical to the 
random read operation with the addition of error code 05, which 
indicates that a new extent cannot be created due to directory 
overflow. 
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Function 35: Compute File Size 

Entry Parameters: 

Register C: 23H 
Registers DE: FCB Address 

Returned Value: 

Random Record Field Set 

When computing the size of a file, the DE register pair addresses 
an FCB in random mode format (bytes rO, r1 , and r2 are present). 
The FCB contains an unambiguous file name which is used in 
the directory scan. Upon return, the random record bytes contain 
the "virtual" file size which is, in effect, the record address of the 
record following the end of the file. If, following a call to function 
35, the high record byte r2 is 01 , then the file contains the 
maximum record count 65536. Otherwise, bytes rO and r1 constitute 
a 16-bit value (rO is the least significant byte, as before) which is 
the file size. 

Data can be appended to the end of an existing file by simply 
calling function 35 to set the random record position to the end 
of file, then performing a sequence of random writes starting at the 
preset record address. 

The virtual size of a file corresponds to the physical size when 
the file is written sequentially. If, instead, the file was created in 
random mode and "holes" exist in the allocation, then the file 
may in fact contain fewer records than the size indicates. If, for 
example, only the last record of an eight megabyte file is written 
in random mode (i.e., record number 65535), then the virtual size 
in 65536 records, although only one block of data is actually 
allocated. 
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Function 36: Set Random Record 

Entry Parameters: 

Register C: 24H 
Registers DE: FCB Address 

Returned Value: 

Random Record Field Set 

The Set Random Record function causes the BDOS to automatically 
produce the random record position from a file which has been 
read or written sequentially to a particular point. The function can 
be useful in two ways. 

First, it is often necessary to initially read and scan a sequential 
file to extract the position of various "key" fields. As each key is 
encountered, function 36 is called to compute the random record 
position for the data corresponding to this key. If the data unit size 
is 128 bytes, the resulting record position is placed into a table 
with the key for later retrieval. After scanning the entire file and 
tabularizing the keys and their record numbers, you can move 
instantly to a particular keyed record by performing a random read 
using the corresponding random record number which was saved 
earlier. The scheme is easily generated when variable record 
lengths are involved since the program need only store the 
buffer-relative byte position along with the key and record number 
in order to find the exact starting position of the keyed data at a 
later time. 

A second use of function 36 occurs when switching from a 
sequential read or write over to random read or write. A file is 
sequentially accessed to a particular point in the file, function 36 is 
called which sets the record number, and subsequent random 
read and write operations continue from the selected point in the 
file. 
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Sample File-to-File Copy Program 



The program shown below provides a relatively simple example of 
file operations. The program source file is created as COPY.ASM 
using the CP/M ED program and then assembled using ASM or 
MAC, resulting in a "HEX" file. The LOAD program is then used 
to produce a COPY.COM file which executes directly under the 
CCP The program begins by setting the stack pointer to a local 
area, and then proceeds to move the second name from the default 
area at 006CH to a 33-byte file control block called DFCB. The 
DFCB is then prepared for file operations by clearing the current 
record field. At this point, the source and destination FCB's are 
ready for processing since the SFCB at 005CH is properly set-up 
by the CCP upon entry to the COPY program. That is, the first 
name is placed into the default FCB, with the proper fields zeroed, 
including the current record field at 007CH. The program 
continues by opening the source file, deleting any existing 
destination file, and then creating the destination file. If all this is 
successful, the program loops at the label COPY until each 
record has been read from the source file and placed into the 
destination file. Upon completion of the data transfer, the destination 
file is closed and the program returns to the CCP command level 
by jumping to BOOT. 

; SAMPLE FILE-TO-FILE COPY PROGRAM 

; AT THE CCP LEVEL, THE COMMAND 

COPYA:X.YB:UV 



COPIES THE FILE NAMED X.Y FROM DRIVE 
A TO A FILE NAMED U.VON DRIVE B. 



0000 




BOOT 


EQU 


0000 H 


SYSTEM REBOOT 


0005 




BDOS 


EQU 


0005 H 


BDOS ENTRY POINT 


005C 




FCB1 


EQU 


005CH 


FIRST FILE NAME 


005C 




SFCB 


EQU 


FCB1 


SOURCE FCB 


006C 




FCB2 


EQU 


006CH 


SECOND FILE NAME 


0080 




DBUFF 


EQU 


0080 H 


DEFAULT BUFFER 


0100 




TPA 


EQU 


0100H 


BEGINNING OF TPA 


0009 




PRINTF 


EQU 


9 


PRINT BUFFER FUNCs 


000 F 




OPENF 


EQU 


15 


OPEN FILE FUNCa 


0010 




CLOSEF 


EQU 


16 


CLOSE FILE FUNCa 


0013 




DELETEF 


EQU 


19 


DELETE FILE FUNC* 


0014 




READF 


EQU 


20 


SEQUENTIAL READ 


0015 




WRITEF 


EQU 


21 


SEQUENTIAL WRITE 


0016 




MAKEF 


EQU 


22 


MAKE FILE FUNCs 


0100 






ORG 


TPA 


BEGINNING OF TPA 


0100 


311B02 




LXI 


SR STACK 


LOCAL STACK 
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MOVE SECOND FILE NAME TO DFCB 


0103 


OE10 


MVI 


C.16 


HALF AN FCB 


0105 


1 1 6C00 


LXI 


D.FCB2 


SOURCE OF MOVE 


0108 


2 1 DA0 1 


LXI 


H.DFCB 


DESTINATION FCB 


010B 


1A 


MFCB: LDAX 


D 


SOURCE FCB 


01 OC 


13 


INX 


D 


READY NEXT 


010D 


77 


MOV 


M.A 


DEST FCB 


010E 


23 


INX 


H 


READY NEXT 


010F 


OD 


DCR 


C 


COUNT 16.0 


01 10 


C20B01 


JNZ 


MFCB 


LOOP 16 TIMES 






NAME HAS BEEN MOVED, ZERO CR 


0113 


AF 


XRA 


A 


A = 00H 


0114 


32FA01 


STA 


DFCBCR 


CURRENT REC = 






SOURCE AND DESTINATION FCB S READY 


0117 


1 1 5C00 


LXI 


D.SFCB 


SOURCE FILE 


01 1 A 


CD6901 


CALL 


OPEN 


ERROR IF 255 


01 1 D 


1 18701 


LXI 


D.NOFILE 


READY MESSAGE 


01 20 


3C 


INR 


A 


255 BECOMES 


0121 


CC6101 


CZ 


FINIS 


DONE IF NO FILE 






SOURCE 


FILE OFEN, PREP DESTINATION 


01 24 


1 1 DA01 


LXI 


D.DFCB 


DESTINATION 


0127 


CD7301 


CALL 


DELETE 


REMOVE IF PRESENT 


01 2A 


1 1 DA0 1 


LXI 


D.DFCB 


DESTINATION 


01 2D 


CD8201 


CALL 


MAKE 


CREATE THE FILE 


01 30 


1 1 9601 


LXI 


D.NODIR 


READY MESSAGE 


0133 


3C 


INR 


A 


255 BECOMES 


0134 


CC6101 


CZ 


FINIS 


DONE IF NO DIR SPACE 






SOURCE 


FILE OPEN. DEST FILE OPEN 






COPY UNTIL END OF FILE ON SOURCE 


0137 


1 15C00 


COPY: LXI 


D.SFCB 


SOURCE 


013A 


CD7801 


CALL 


READ 


READ NEXT RECORD 


013D 


B7 


ORA 


A 


END OF FILE? 


013E 


C25101 


JNZ 


EOFILE 


SKIP WRITE IF SO 






NOT END OF FILE. WRITE THE RECORD 


0141 


11DA01 


LXI 


D.DFCB 


DESTINATION 


0144 


CD7D01 


CALL 


WRITE 


WRITE RECORD 


0147 


11A901 


LXI 


D, SPACE 


READY MESSAGE 


014A 


B7 


ORA 


A 


00 IF WRITE OK 


014B 


C46101 


CNZ 


FINIS 


END IF SO 


014E 


C33701 


JMP 


COPY 


LOOP UNTIL EOF 




EOFILE: ; END OF FILE, CLOSE DESTINATION 


0151 


1 1 DA01 


LXI 


D.DFCB 


DESTINATION 


01 54 


CD6E01 


CALL 


CLOSE 


255 IF ERROR 


0157 


21BB01 


LXI 


H.WRPROT 


READY MESSAGE 


01 5A 


3C 


INR 


A 


255 BECOMES 00 


01 5B 


CC6101 


CZ 


FINIS 


SHOULDN'T HAPPEN 






COPY OPERATION COMPLETE, END 


015E 


11CC01 


LXI 


D. NORMAL 


READY MESSAGE 






FINIS: : WRITE MESSAGE GIVEN BY DE. REBOOT 


0161 


0E09 


MVI 


C.PRINTF 




0163 


CD0500 


CALL 


BDOS 


WRITE MESSAGE 


0166 


C30000 


JMP 


BOOT 


REBOOT SYSTEM 



SYSTEM INTERFACE SUBROUTINES 
(ALL RETURN DIRECTLY FROM BDOS) 



0169 OEOF OPEN: MVI C. OPENF 
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016B 


C30500 




JMP 


BDOS 


016E 
0170 


0E10 
C30500 


CLOSE: 


MVI 
JMP 


C.CLOSEF 
BDOS 


0173 
0175 


0E13 
C30500 


DELETE: 


MVI 
JMP 


CDELETEF 
BDOS 


0178 
01 7A 


0E14 
C30500 


READ: 


MVI 
JMP 


CREADF 
BDOS 


017D 
017F 


0E15 
C30500 


WRITE: 


MVI 
JMP 


C.WRITEF 
BDOS 


0182 
0184 


0E16 
C30500 


MAKE: 


MVI 
JMP 


C.MAKEF 
BDOS 


0187 
0196 
01A9 
01BB 
01CC 


6E6F20FNOFILE: 

6E6F209NODIR' 

6F7574FSPACE: 

7772695WRPROT: 

636F700NORMAL: 


CONSOLE MESSAGES 

DB NO SOURCE FILES 

DB NO DIRECTORY SPACES 

DB OUT OF DATA SPACES 

DB WRITE PROTECTED-?* 

DB COPY COMPLETES 


01 DA 
01 FA 




DFCB: 
DFCBCR 


DATA AREAS 

DS 33 : DESTINATION FCB 
EQU DFCB + 32 : CURRENT RECORD 


01 FB 
021 B 




STACK: 


DS 
END 


32 : 16 LEVEL STACK 



Note that there are several simplifications in this particular 
program. First, there are no checks for invalid file names which 
could, for example, contain ambiguous references. This situation 
could be detected by scanning the 32 byte default area starting at 
location 005CH for ASCII question marks. A check should also 
be made to ensure that the file names have, in fact, been included 
(check locations 005DH and 006DH for non-blank ASCII characters). 
Finally, a check should be made to ensure that the source and 
destination file names are different. A speed improvement could be 
made by buffering more data on each read operation. One could, 
for example, determine the size of memory by fetching FBASE 
from location 0006H and use the entire remaining portion of 
memory for a data buffer. In this case, the programmer simply 
resets the DMA address to the next successive 1 28 byte area 
before each read. Upon writing to the destination file, the DMA 
address is reset to the beginning of the buffer and incremented 
by 128 bytes to the end as each record is transferred to the 
destination file. 
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Sample File Dump Utility 



The file dump program shown below is slightly more complex 
than the single copy program given in the previous section. The 
dump program reads an input file, specified in the CCP command 
line, and displays the content of each record in hexadecimal format 
at the console. Note that the dump program saves the CCP's 
stack upon entry, resets the stack to a local area, and restores the 
CCP's stack before returning directly to the CCP. Thus, the dump 
program does not perform warm start at the end of processing. 



DUMP PROGRAM READS INPUT FILE AND DISPLAYS HEX DATA 



0100 






ORG 100H 




0005 


... 


BDOS 


EOU 0005H 


DOS ENTRY POINT 


0001 




CONS 


EQU 1 


READ CONSOLE 


0002 


= 


TYPEF 


EQU 2 


TYPE FUNCTION 


0009 




PRINTF 


EQU 9 


BUFFER PRINT ENTRY 


000 B 


= 


BRKF 


EQU 1 1 


BREAK KEY FUNCTION (TRUE IF CHAR 


000 F 


= 


OPENF 


EQU 15 


FILE OPEN 


0014 




READF 


EQU 20 


READ FUNCTION 


005C 




FCB 


EQU 5CH 


FILE CONTROL BLOCK ADDRESS 


0080 


= 


BUFF 


EQU 80H 


INPUT DISK BUFFER ADDRESS 








NON GRAPHIC CHARACTERS 


000 D 






EQU ODH 


CARRIAGE RETURN 


000A 




[_p 


EQU OAH 


LINE FEED 








FILE CONTROL BLOCK DEFINITIONS 


005C 




FCBDN 


EQU FCB+0 


DISK NAME 


005 D 




FCBFN 


EQU FCB+1 


FILE NAME 


0065 




FCBFT 


EQU FCB+9 


DISK FILE TYPE (3 CHARACTERS) 


0068 




FCBRL 


EQU FCB+12 


FILE S CURRENT REEL NUMBER 


006 B 




FCBRC 


EQU FCB + 15 


FILE S RECORD COUNT (0 TO 128) 


007C 




FCBCR 


EQU FCB+32 


CURRENT(NEXT) RECORD NUMBER (0) 


007D 




FCBLN 


EQU FCB + 33 


FCB LENGTH 








SET UP STACK 




0100 


210000 




LXI H.O 




0103 


39 




DAD SP 










ENTRY STACK POINTER IN HL FROM THE CCP 


0104 


221502 




SHLD OLDSP 










SET SP TO LOCAL STACK AREA (RESTORED AT FINIS) 


0107 


315702 




LXI SP.STKTOP 










READ AND PRINT SUCCESSIVE BUFFERS 


01 OA 


CDC101 




CALL SETUP 


SET UP INPUT FILE 


010D 


FEFF 




CPI 255 


255 IF FILE NOT PRESENT 


010F 


C21B01 




JNZ OPENOK 


SKIP IF OPEN IS OK 








FILE NOT THERE. GIVE ERROR MESSAGE AND RETURN 


0112 


LLF301 




LXI D.OPNMSG 




0115 


CD9C01 




CALL ERR 




0118 


C35101 




JMP FINIS :TO RETURN 






OPENOK: 


:OPEN OPERATION OK 


SET BUFFER INDEX TO END 


011B 


3E80 




MVI A.80H 




011D 


321302 




STA IBP :SET BUFFER POINTER TO 80H 



HL CONTAINS NEXT ADDRESS TO PRINT 
0120 210000 LXI H.O :START WITH 0000 
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GLOOP: 

0123 E5 

0124 CDA201 

0127 E1 

0128 DA5101 
012B 47 



012C 7D 

012D E60F 

012F C24401 

0132 CD7201 



0135 CD5901 

0138 OF 

0139 DA5101 

01 3C 7C 

01 3D CD8F01 

0140 7D 

0141 CD8F01 

NONUM 

0144 23 

0145 3E20 
0147 CD6501 
014A 78 
014B CD8F01 
01 4E C32301 

FINIS: 



0151 CD7201 

0154 2A1502 

0157 F9 

0158 C9 



BREAK: 

0159 E5D5C5 
01 5C OEOB 
015E CDO500 
0161 C1D1E1 

0164 C9 

PCHAR: 

0165 E5D5C5 
0168 0E02 
016A 5F 

01 6B CD0500 
016E C1D1E1 

0171 C9 

CRLF: 

0172 3E0D 
0174 CD6501 
0177 3E0A 
0179 CD6501 
017C C9 



PUSH 


H 


CALL 


GNB 


POP 


H 


JC 


FINIS 


MOV 


B.A 



:SAVE LINE POSITION 



;RECALL LINE POSITION 

: CARRY SET BY GNB IF END FILE 



PRINT HEX VALUES 
CHECK FOR LINE FOLD 
MOV A,L 

ANI OFH :CHECK LOW 4 BITS 

JNZ NONUM 
PRINT LINE NUMBER 
CALL CRLF 

CHECK FOR BREAK KEY 
CALL BREAK 

ACCUM LSB = 1 IF CHARACTER READY 

RRC :INTO CARRY 

JC FINIS ;DONT PRINT ANY MORE 



MOV A.H 

CALL PHEX 

MOV A,L 

CALL PHEX 

|NX H :TO NEXT LINE NUMBER 

MVI A.' 

CALL PCHAR 

MOV A.B 

CALL PHEX 

JMP GLOOP 



END OF DUMP. RETURN TO CCP 
(NOTETHATAJMPTO0000H REBOOTS) 
CALL CRLF 
LHLD OLDSP 
SPHL 

STACK POINTER CONTAINS CCP S STACK LOCATION 
RET :TOTHECCP 



SUBROUTINES 

:CHECK BREAK KEY (ACTUALLY ANY KEY WILL DO) 
PUSH H! PUSH D! PUSH B: ENVIRONMENT SAVED 
MVI CBRKF 
CALL BDOS 

POP B' POP D! POP H: ENVIRONMENT RESTORED 
RET 

:PRINT A CHARACTER 

PUSH H! PUSH D' PUSH B: SAVED 

MVI C.TYPEF 

MOV E.A 

CALL BDOS 

POP B' POP D' POP H; RESTORED 
RET 



MVI A.CR 

CALL PCHAR 

MVI A.LF 

CALL PCHAR 
RET 
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PNIB: 

01 7D E60F 
01 7F FEOA 
0181 D28901 

0184 C630 
0186 C38B01 



0189 C637 P10: 
018B CD6501 PRN: 
018E C9 

PHEX: 

018F F5 

0190 OF 

0191 OF 

0192 OF 

0193 OF 

0194 CD7D01 

0197 F1 

0198 CD7D01 
019B C9 

ERR: 

01 9C 0E09 

01 9E CD0500 

01A1 C9 



GNB 

01A2 3A1302 
01A5 FE80 
01A7 C2B301 



01AA CDCE01 

01AD B7 

01AE CAB301 

01B1 37 

01 B2 C9 

GO: 

01 B3 5F 

01 B4 1600 

01 B6 3C 

01 B7 321302 



01BA 218000 

01BD 19 

01BE 7E 

01BF B7 

01 CO C9 

SETUP' 

01C1 AF 

01C2 327C00 

01C5 115C00 

01C8 OEOF 



;PRINT NIBBLE IN REG A 

ANI OFH :LOW4BITS 

CPI 10 

JNC P10 

LESS THAN OR EQUAL TO 9 

ADI 0' 

JMP PRN 

GREATER OR EQUAL TO 10 
ADI A - 10 

CALL PCHAR 
RET 

PRINT HEX CHAR IN REG A 

PUSH PSW 

RRC 

RRC 

RRC 

RRC 

CALL PNIB PRINT NIBBLE 

POP PSW 
CALL PNIB 
RET 

PRINT ERROR MESSAGE 

D.E ADDRESSES MESSAGE ENDING WITH "$' 

MVI CPRINTF PRINT BUFFER FUNCTION 

CALL BDOS 

RET 



:GET NEXT BYTE 

LDA IBP 

CPI 80H 

JNZ GO 

READ ANOTHER BUFFER 



CALL DISKR 

ORA A :ZERO VALUE IF READ OK 

JZ GO :FOR ANOTHER BYTE 

END OF DATA, RETURN WITH CARRY SET FOR EOF 

STC 

RET 

:READ THE BYTE AT BUFF + REG A 

MOV E.A :1S BYTE OF BUFFER INDEX 

MVI D O ;DOUBLE PRECISION INDEX TO DE 

INR A .INDEX = INDEX+1 

STA IBP PACK TO MEMORY 

POINTER IS INCREMENTED 

SAVE THE CURRENT FILE ADDRESS 

LXI H.BUFF 

DAD D 

ABSOLUTE CHARACTER ADDRESS IS IN H1 
MOV A.M 

BYTE IS IN THE ACCUMULATOR 

ORA A PESET CARRY BIT 

RET 

:SET UP FILE 

OPEN THE FILE FOR INPUT 

XRA A :ZERO TO ACCUM 

STA FCBCR :CLEAR CURRENT RECORD 

LXI D.FCB 
MVI C.OPENF 
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DISKR: 



01CA CD0500 
01CD C9 



01CE E5D5C5 

01 D1 115C00 

01D4 0E14 

01 D6 CD0500 

01D9 C1D1E1 

01 DC C9 



01 DD 46494C0SIGNON: 
01 F3 0D0A4E0OPNMSG: 



CALL BDOS 

255 IN ACCUM IF OPEN ERROR 

RET 

;READ DISK FILE RECORD 
PUSH H! PUSH D! PUSH B 
LXI D.FCB 
MVI CREADF 
CALL BDOS 
POP B! POP D! POP H 
RET 

FIXED MESSAGE AREA 

DB FILE DUMP VERSION 2.0$ 

DB CR.LF. NO INPUT FILE PRESENT ON DISKS 



0213 IBP: 
0215 OLDSP: 



STKTOP: 



VARIABLE AREA 
DS 2 
DS 2 

STACK AREA 
DS 64 



;INPUT BUFFER POINTER 
;ENTRY SP VALUE FROM CCP 



;RESERVE 32 LEVEL STACK 



Sample Random Access Program 



This manual is concluded with a rather extensive, but complete 
example of random access operation. The program listed below 
performs the simple function of reading or writing random records 
upon command from the terminal. Given that the program has been 
created, assembled, and placed into a file labelled RANDOM.COM, 
the CCP level command: 

RANDOM X.DAT 

starts the test program. The program looks for a file by the name 
X.DAT (in this particular case) and, if found, proceeds to prompt the 
console for input. If not found, the file is created before the 
prompt is given. Each prompt takes the form 

next command? 

and is followed by operator input, terminated by a carriage return. 
The input commands take the form 

nW nR Q 

where n is an integer value in the range to 65535, and W, R, 
and Q are simple command characters corresponding to random 
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write, random read, and quit processing, respectively. If the W 
command is issued, the RANDOM program issues the prompt 



type data: 



The operator then responds by typing up to 127 characters, followed 
by a carriage return. RANDOM then writes the character string 
into the X.DAT file at record n. If the R command is issued, 
RANDOM reads record number n and displays the string value at 
the console. If the Q command is issued, the X.DAT file is closed, 
and the program returns to the console command processor. In 
the interest of brevity, the only error message is 

error, try again 

The program begins with an initialization section where the input 
file is opened or created, followed by a continuous loop at the 
label "ready" where the individual commands are interpreted. The 
default file control block at 005CH and the default buffer at 
0080H are used in all disk operations. The utility subroutines then 
follow, which contain the principal input line processor, called 
"readc." This particular program shows the elements of random 
access processing, and can be used as the basis for further 
program development. 



* SAMPLE RANDOM ACCESS PROGRAM FOR CP/M 2.0 









* * * # * 






0100 






ORG 


100H 


: BASE OF TPA 


0000 




REBOOT 


EQU 


OOOOH 


; SYSTEM REBOOT 


0005 




BDOS 


EQU 


0005 H 


; BDOS ENTRY POINT 


0001 




CONINP 


EQU 


1 


; CONSOLE INPUT FUNCTION 


0002 




CONOUT 


EQU 


2 


; CONSOLE OUTPUT FUNCTION 


0009 




PSTRING 


EQU 


9 


; PRINT STRING UNTIL $ 


000A 




RSTRING 


EQU 


10 


; READ CONSOLE BUFFER 


OOOC 




VERSION 


EQU 


12 


; RETURN VERSION NUMBER 


000 F 




OPENF 


EQU 


15 


; FILE OPEN FUNCTION 


0010 




CLOSEF 


EQU 


16 


; CLOSE FUNCTION 


0016 




MAKEF 


EQU 


22 


; MAKE FILE FUNCTION 


0021 




READR 


EQU 


33 


; READ RANDOM 


0022 




WRITER 


EQU 


34 


; WRITE RANDOM 


005C 




FCB 


EQU 


005CH 


; DEFAULT FILE CONTROL BLOCK 
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007 D = 


RANREC 


EQU 


FCB + 33 


: RANDOM RECORD POSITION 


007 F = 


RANOVF 


EQU 


FCB + 35 


; HIGH ORDER (OVERFLOW) BYTE 


0080 = 


BUFF 


EQU 


0080H 


: BUFFER ADDRESS 


000 D = 


CR 


EQU 


ODH 


: CARRIAGE RETURN 


000A = 


LF 


EQU 


OAH 


LINE FEED 



: • LOAD SP. SET-UP FILE FOR RANDOM ACCESS 
0100 31BC0 LXI S P. STACK 



0103 OEOC 

0105 CD050 

0108 FE20 

010A D2160 

010D 1 1 1 BO 

0110 CDDAO 

0113 C3000 



VERSION 2.0? 

MVI C. VERSION 

BDOS 

CPI 20H : VERSION 2.0 OR BETTER? 

JNC VERSOK 

BAD VERSION, MESSAGE AND GO BACK 
LXI DBADVER 
CALL PRINT 
JMP REBOOT 



VERSOK: 



0116 OEOF 

0118 11 SCO 

01 1B CD050 

01 1E 3C 

01 1F C2370 



CORRECT VERSION FOR RANDOM ACCESS 
MVI C.OPENF OPEN DEFAULT FCB 

LXI D.FCB 
CALL BDOS 

INR A : ERR 255 BECOMES ZERO 

JNZ READY 



0122 0E16 

0124 11 SCO 

0127 CD050 

012A 3C 

012B C2370 



CANNOT OPEN FILE. SO CREATE IT 
MVI C.MAKEF 
LXI D.FCB 
CALL BDOS 

INR A ; ERR 255 BECOMES ZERO 

READY 



012E 113A0 
0131 CDDAO 
0134 C3000 



CANNOT CREATE FILE. DIRECTORY FULL 
LXI D.NOSPACE 
CALL PRINT 

JMP REBOOT :BACKTOCCP 



LOOP BACK TO READY' AFTER EACH COMMAND 



FILE IS READY FOR PROCESSING 



0137 CDE50 CALL 

013A 227D0 SHLD 

013D 217F0 LXI 

0140 3600 MVI 

0142 FE51 CPI 

0144 C2560 JNZ 



READCOM ; READ NEXT COMMAND 

RANREC ; STORE INPUT RECORD* 
H, RANOVF 

M.O ; CLEAR HIGH BYTE IF SET 

Q' :QUIT? 

NOTQ 



QUIT PROCESSING. CLOSE FILE 



0147 
0149 
014C 
014F 
0150 
0153 



0E10 
1 15C0 
CD050 
3C 

CAB90 
C3000 



MVI 

LXI 

CALL 

INR 

JZ 

JMP 



C. CLOSEF 

D. FCB 
BDOS 
A 

ERROR 
REBOOT 



ERR 255 BECOMES 
ERROR MESSAGE. RETRY 
BACK TO CCP 
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:* END OF QUIT COMMAND. PROCESS WRITE 

















NOTQ: 












NOT THE QUIT COMMAND. RANDOM WRITE 9 


0156 


FE57 




CPI 


W 


0158 


C2890 




JNZ 


NOTW 








THIS IS A RANDOM WRITE. FILL BUFFER UNTIL CR 


015B 


1 14D0 




LXI 


D.DATMSG 


015E 


CDDAO 




CALL 


PRINT : DATA PROMPT 


0161 


0E7F 




MVI 


C127 : UP TO 127 CHARACTERS 


0163 


21800 




LXI 


H BUFF DESTINATION 






RLOOP: 


; READ NEXT CHARACTER TO BUFF 


0166 


C5 




PUSH 


B SAVE COUNTER 


0167 


E5 




PUSH 


H : NEXT DESTINATION 


01 68 


CDC20 




CALL 


GETCHR .CHARACTER TO A 


016B 


E1 




POP 


H ; RESTORE COUNTER 


01 6C 


C1 




POP 


B ; RESTORE NEXT TO FILL 


016D 


FEOD 




CPI 


CR : END OF LINE? 


016F 


CA780 




JZ 


ERLOOP 








NOT END, 


STORE CHARACTER 


0172 


77 




MOV 


MA 


0173 


23 




INX 


H : NEXT TO FILL 


0174 


OD 




DCR 


C : COUNTER GOES DOWN 


0175 


C2660 




JNZ 


RLOOP : END OF BUFFER' 






ERLOOP 












END OF READ LOOP STORE 00 


01 78 


3600 




MVI 


M.O 








WRITE THE RECORD TO SELECTED RECORD NUM 


017A 


0E22 




MVI 


C.WRITER 


017C 


1 15C0 




LXI 


D.FCB 


017F 


CD050 




CALL 


BDOS 


0182 


B7 




ORA 


A : ERROR CODE ZERO? 


0183 


C2B90 




JNZ 


ERROR : MESSAGE IF NOT 


0186 


C3370 




JMP 


READY . FOR ANOTHER RECORD 
















:• END OF WRITE COMMAND. PROCESS READ 













NOTW 

NOT A WRITE COMMAND, READ RECORD? 



0189 


FE52 


CPI 


R 




018B 


C2B90 


JNZ 


ERROR 


SKIP IF NOT 






READ RANDOM RECORD 


018E 


0E21 


MVI 


C.READR 




0190 


1 15C0 


LXI 


D.FCB 




0193 


CD050 


CALL 


BDOS 




0196 


B7 


ORA 


A 


RETURN CODE 00? 


0197 


C2B90 


JNZ 


ERROR 








READ WAS SUCCESSFUL, WRITE TO CONSOLE 


019A 


CDCFO 


CALL 


CRLF 


NEW LINE 


01 9D 


0E80 


MVI 


C.128 


MAX 128 CHARACTERS 


019F 


21800 


LXI 


H.BUFF 


NEXT TO GET 




WLOOP: 








01A2 


7E 


MOV 


A.M 


NEXT CHARACTER 


01 A3 


23 


INX 


H 


NEXT TO GET 


01 A4 


E67F 


AN I 


7FH 


MASK PARITY 
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01 A6 


CA370 


JZ READY , rUH ANUIHtH tUMMANL) lr OC 








READC: 


LDAX 


D 


INtAI UUIVIIvIAInU UMAnAUl tn 


01 A9 


C5 


PUSH B ; SAVE COUNTER 




01 FA 


13 




INX 


D 


TO NEXT COMMAND POSITION 


01 AA 


E5 


PUSH H ; SAVE NEXT TO GET 




01 FB 


B7 




ORA 


A 


CANNOT BE END OF COMMAND 


01 AB 


FE20 


CPI ; GRAPHIC? 




01 FC 


C8 




RZ 






01 AD 


D4C80 


CNC PUTCHR ; SKIP OUTPUT IF NOT 










NOT ZERO, NUMERIC? 




01 BO 


E1 


POP H 




01 FD 


D630 




SUI 


'0' 




01 B1 


C1 


POP B 




01 FF 


FEOA 




CPI 


10 


CAHHY lr NUMERIC 


01 B2 


OD 


DCR C ; COUNT=COUNT-1 




0201 


D2130 




JNC 


ENDRD 




01 B3 


C2A20 


JNZ WLOOP 










ADD-IN NEXT DIGIT 




01 B6 


C3370 


JMP READY 




0204 
0205 


29 
4D 




DAD 
MOV 


H 

C.1 


*2 






*********************************************** 




0206 


44 




MOV 


B.H 


Dlj — VALUt ^ 










0207 


29 




DAD 


H 








* END OF READ COMMAND, ALL ERRORS END-UP HERE 




0208 


29 




DAD 


H 


*8 






* 




0209 


09 




DAD 


B 


«2 + *8 = *10 






*********************************************** 




020A 
020B 


85 
6F 




ADD 
MOV 


1 

1,A 


+ DIGIT 






ERROR: 




020C 


D2F90 




JNC 


READC 


FOR ANOTHER CHAR 


01 B9 


1 1590 


LXI D.ERRMSG 




020F 


24 




INR 


H 


OVERFLOW 


01 BC 


CDDAO 


CALL PRINT 




021 


C3F90 




JMP 


READC 


FOR ANOTHER CHAR 


01 BF 


C3370 


JMP READY 








ENDRD: 






















END OF READ, RESTORE VALUE IN A 






*********************************************** 


* 


0213 


C630 




ADI 


0' 


COMMAND 






* 




0215 


FE61 




CPI 


A 


TRANSLATE CASE? 






* UTILITY SUBROUTINES FOR CONSOLE I/O 


* 


0217 


D8 




RC 




















LOWER CASE, MASK LOWER CASE BITS 








• 


0218 


E65F 




AN I 


1 01 S1 1 1 1 B 






GETCHR: 




021 A 


C9 




RET 










; READ NEXT CONSOLE CHARACTER TO A 
















01C2 


0E01 


MVI CCONINP 








******* 








01 C4 
01C7 


CD050 
C9 


CALL BDOS 
RET 








* STRING DATA AREA FOR CONSOLE MESSAGE 




PUTCHR: 
















01 C8 


0E02 


; WRITE CHARACTER FROM A TO CONSOLE 
MVI CCONOUT 




021 B 


536F79 


BADVER: 


DB 


SORRY, YOU NEED CP/M VERSION 2$ 


01 CA 


5F 


MOV E,A ; CHARACTER TO SEND 






NOSPACE: 








01CB 


CD050 


CALL BDOS ; SEND CHARACTER 




023A 


4E6F29 




DB 


NO DIRtC I UHY bmLt» 


01CE 


C9 


RET 






DATMSG: 












024 D 


547970 




DB 


TYPE DAI A: I 




CRI F 








ERRMSG: 












; SEND CARRIAGE RETURN LINE FEED 




0259 


457272 




DB 


ERROR, TRY AGAIN. 5 


01CF 


3E0D 


MVI A.CR ; CARRIAGE RETURN 








PROMPT: 








01D1 


CDC80 


CALL PUTCHR 




026B 


4E6570 




DB 


NEXT COMMAND r » 


01 D4 
01 D6 


3E0A 
CDC80 


MVI A.LF ; LINE FEED 
CALL PUTCHR 
















01 D9 


C9 


RET 






















* FIXED AND VARIABLE DATA AREA 






PRINT: 




















; PRINT THE BUFFER ADDRESSED BY DE UNTIL $ 










******* 






01 DA 
01 DB 
01 DE 


D5 

CDCFO 
D1 


PUSH D 
CALL CRLF 

POP D ; NEW LINE 




027A 


21 


CONBUF: 


DB 


CONLEN 


LENGTH OF CONSOLE BUFFER 




027B 
027C 




CONSIZE: 
CONLIN: 


DS 
DS 


1 

32 


RESULTING SIZE AFTER READ 
LENGTH 32 BUFFER 


01 DF 


0E09 


MVI CPSTRING 




0021 




CONLEN 


EQU 


$-CONSIZ 




01 E1 
01 E4 


CD050 
C9 


CALL BDOS ; PRINT THE STRING 
RET 

READCOM: 

; READ THE NEXT COMMAND LINE TO THE CONBUF 




029C 
02 BC 




STACK: 


DS 
END 


32 


16 LEVEL STACK 


01 E5 


116B0 


Lxi D, PROMPT 
















01 E8 


CDDAO 


CALL PRINT ; COMMAND? 
















01EB 


OEOA 


MVI CRSTRING 
















01 ED 


117A0 


LXI D,CONBUF 
















01 FO 


CD050 


CALL BDOS ;FIEAD COMMAND LINE 
COMMAND LINE IS PRESENT, SCAN IT 
















01 F3 


21000 


LXI H,0 ; START WITH 0000 
















01 F6 


117C0 


LXI D,CONLIN ; COMMAND LINE 

















90 CP/M Reference Manual 



Again, major improvements could be made to this particular 
program to enhance its operation. In fact, with some work, this 
program could evolve into a simple data base management 
system. One could, for example, assume a standard record size of 
1 28 bytes, consisting of arbitrary fields within the record. A 
program, called GETKEY, could be developed which first reads a 
sequential file and extracts a specific field defined by the operator. 
For example, the command 

GETKEY NAMES.DAT LASTNAME 10 20 

would cause GETKEY to read the data base file NAMES.DAT and 
extract the "LASTNAME" field from each record, starting at 
position 10 and ending at character 20. GETKEY builds a table in 
memory consisting of each particular LASTNAME field, along 
with its 16-bit record number location within the file. The GETKEY 
program then sorts this list, and writes a new file, called 
LASTNAME. KEY, which is an alphabetical list of LASTNAME 
fields with their corresponding record numbers. (This list is called 
an "inverted index" in information retrieval parlance.) 

Rename the program shown above as QUERY, and massage it a 
bit so that it reads a sorted key file into memory. The command line 
might appear as: 

QUERY NAMES.DAT LASTNAME. KEY 

Instead of reading a number, the QUERY program reads an 
alphanumeric string which is a particular key to find in the 
NAMES.DAT data base. Since the LASTNAME. KEY list is sorted, 
you can find a particular entry quite rapidly by performing a 
"binary search," similar to looking up a name in the telephone 
book. That is, starting at both ends of the list, you examine the 
entry halfway in between and, if not matched, split either the upper 
half or the lower half for the next search. You'll quickly reach the 
item you're looking for (in log2(n) steps) where you'll find the 
corresponding record number. Fetch and display this record at 
the console, just as we have done in the program shown above. 

At this point you're just getting started. With a little more work, you 
can allow a fixed grouping size which differs from the 128 byte 
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record shown above. This is accomplished by keeping track of the 
record number as well as the byte offset within the record. 
Knowing the group size, you randomly access the record containing 
the proper group, offset to the beginning of the group within the 
record read sequentially until the group size has been exhausted. 

Finally, you can improve QUERY considerably by allowing boolean 
expressions which compute the set of records which satisfy 
several relationships, such as a LASTNAME between HARDY and 
LAUREL, and an AGE less than 45. Display all the records which 
fit this description. Finally, if your lists are getting too big to fit into 
memory, randomly access your key files from the disk as well. 
One note of consolation after all this work: if you make it through 
the project, you'll have no more need for this manual! 
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System Function Summary 







Input 


Output 


Func 


Function Name 


Parameters 


Results 


o 


Sv^tpm Rp^pt 


none 


none 


1 


Console Input 


none 


A=char 


2 


Console Output 


E=char 


none 


3 


Reader Input 


none 


A=char 


4 


Punch OutDut 


E=char 


none 


5 


1 i^t Outnut 


E=char 


none 


6 


Direct Console I/O 


see def 


see def 


7 


Get I/O Bvte 


none 


A=IOBYTE 


« 


Spt I/O Rvtp 


E=I0BYTE 


none 


q 


Print Strina 

i iiiil \j ii ii i y 


DE=. Buffer 


none 


m 


Rp?irl Pon<5olp Rnffpr 


DE=. Buffer 


see def 


1 1 

l l 


fnPt Pnncnlp Status 


none 


A=00/FF 


1 2 


Rpturn V/pr^ion Numhpr 

nCLUI 1 1 VUI OIUI 1 INUIIIk-/C^I 


none 


HL=Version* 


1 ^ 

1 O 


Ppcpf Hick fivotpm 
ncoci L/ioi\ oyoici 1 1 


none 


see def 


14 


Selpct Disk 


E=Disk Number 


see def 


1 *S 


f)npn Filp 


DE=.FCB 


A=DirCode 


1 R 


PIoqp Filp 


DE^.FCB 


A=Dir Code 


1 7 

1 / 


Sparnh for Fir^t 

UvUl Ul 1 1 \J 1 1 II OL 


DE=.FCB 


A=DirCode 


18 


Sparnh for Npxt 


none 


A=Dir Code 


19 


Hplptp File 


DE=.FCB 


A=Dir Code 


20 


Read Seauential 


DE" FCB 


A=Err Code 


21 


Write Sequential 


DE=.FCB 


A=Err Code 


22 


Mpkp Filp 


DE=.FCB 


A=DirCode 


23 


Rpnamp Filp 

1 1 \— / 1 1 L-A III V-/ 1 II \s 


DE=.FCB 


A=DirCode 


24 


Return Loain Vector 

1 l\j LUI 1 1 L_\_/ y 1 1 1 V V_r I 


none 


HL=Login Vect* 


25 


Return Current Disk 


none 


A=Cur Disk# 


26 


Set DMA Address 


DE=.DMA 


none 


27 


Get Addr(Allor) 


none 


HL=.AIIoc 


28 


Writp Protect Disk 

V V 1 1 IC 1 1 UlCywl I—/ 1 O l\ 


none 


see def 


29 


Get R/0 Vector 


none 


HL= R/O Vect* 


30 


Set File Attributes 


DE- FCB 


see def 


31 


Get Addr (disk parms) 


none 


HL=.DPB 


32 


Set/Get User Code 


see def 


see def 


33 


Read Random 


DE=.FCB 


A=Err Code 


34 


Write Random 


DE^.FCB 


A=Err Code 


35 


Compute File Size 


DE=.FCB 


rO, r1, r2 


36 


Set Random Record 


DE=.FCB 


rO, r1, r2 



*Note the A=L, and B=H upon return 
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3 

CP INI Editor 



Introduction to ED 



ED is the context editor for CP/M, and is used to create and alter 
CP/M source files. ED is initiated in CP/M by typing 

!<filename> ) 
<filename> ■ <filetype> ; 

In general, ED reads segments of the source file given by 
<filename> or <filename> • <filetype> into central memory, where 
the file is manipulated by the operator, and subsequently written 
back to disk after alterations. If the source file does not exist before 
editing, it is created by ED and initialized to empty. The overall 
operation of ED is shown in Figure 1 . 
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ED Operation 



ED operates upon the source file, denoted in Figure 1 by x.y, 
and passes all text through a memory buffer where the text can be 
viewed or altered (the number of lines which can be maintained 
in the memory buffer varies with the line length, but has a total 
capacity of about 6000 characters in a 16K CP/M system). Text 
material which has been edited is written onto a temporary work 
file under command of the operator. Upon termination of the 
edit, the memory buffer is written to the temporary file, followed by 
any remaining (unread) text in the source file. The name of the 
original file is changed from x.y to x.BAK so that the most recent 
previously edited source file can be reclaimed if necessary (see 
the CP/M commands ERASE and RENAME). The temporary file is 
changed from x.$$$ to x.y which becomes the resulting edited 
file. 

The memory buffer is logically between the source file and working 
file as shown in Figure 2. 

Text Transfer Functions 



Given that n is an integer value in the range through 65535, the 
following ED commands transfer lines of text from the source file 
through the memory buffer to the temporary (and eventually final) 
file: 
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Figure 1. Overall ED Operation 



Source 
Libraries 



R 



Source 
File 

X.Y 



Append 
(A) 



Memory 
Buffer 



[after edit 



insert 
(E) 



Backup 
File 

X.BAK 



Write 
(W) 



type 
(T) 



Temporary 
File 

X.$$$ 



after edit 
(E) 



New 

Source 

File 

X.Y 
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Note 

The ED program accepts both lower and upper case 
ASCII characters as input from the console. Single letter 
commands can be typed in either case. The U command 
can be issued to cause ED to translate lower case 
alphabetics to upper case as characters are filled to 
the memory buffer from the console. Characters are echoed 
as typed without translation, however. The — U command 
causes ED to revert to "no translation" mode. ED starts 
with an assumed — U in effect. 



Figure 2. Memory Buffer Organization 



Source File 



SP-» 



first line 



appended 
lines 



unprocessed 

source 

lines 



Memory Buffer 



MP- 

nexf 
Append 



first line 



buffered 
text 



free 

memory 
space 



Temporary File 




next 
Write 



first line 



processed 
text 



free 

file 

space 
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Figure 3. Logical Organization of Memory Buffer 



Memory Buffer 



first line 


cr If 


current 
line CL 

last 
line 


A cr If 

CP 

cr If 


nA<cr>* 


Append the next n unprocessed source 
lines from the source file at SP to the end of 
the memory buffer at MP. Increment SP and 
MP by n. 


nW<cr> 


Write the first n lines of the memory buffer 
to the temporary file free space. Shift the 
remaining lines n + 1 through MP to the top 
of the memory buffer. Increment TP by n. 


E<cr> 


End the edit. Copy all buffered text to 
temporary file, and copy all unprocessed 
source lines to tne temporary Tile. Hename 
files as described previously. 


H<cr> 


Move to head of new file by performing 
automatic E command. Temporary file 
becomes the new source file, the memory 
buffer is emptied, and a new temporary file 
is created (equivalent to issuing an E 
command, followed by a reinvocation of ED 
using x.y as the file to edit). 



* cr represents the carriage-return key 



CP/M Editor 99 



0<cr> Return to original file. The memory buffer 

is emptied, the temporary file is deleted, 
and the SP is returned to position 1 of the 
source file. The effects of the previous 
editing commands are thus nullified. 

Q<cr> Quit edit with no file alterations, return 

to CP/M. 

There are a number of special cases to consider. If the integer n is 
omitted in any ED command where an integer is allowed, then 1 
is assumed. Thus, the commands A and W append one line and 
write 1 line, respectively. In addition, if a pound sign (#) is given 
in the place of n, then the integer 65535 is assumed (the largest 
value for n which is allowed). Since most reasonably sized 
source files can be contained entirely in the memory buffer, the 
command #A is often issued at the beginning of the edit to read 
the entire source file to memory. Similarly, the command #W writes 
the entire buffer to the temporary file. Two special forms of the A 
and W commands are provided as a convenience. The command 
OA fills the current memory buffer to at least half-full, while OW 
writes lines until the buffer is at least half empty. It should also be 
noted that an error is issued if the memory buffer size is exceeded. 
The operator may then enter any command (such as W) which does 
not increase memory requirements. The remainder of any partial 
line read during the overflow will be brought into memory on the 
next successful append. 

Memory Buffer Organization 



The memory buffer can be considered a sequence of source lines 
brought in with the A command from a source file. The memory 
buffer has an associated (imaginary) character pointer (CP) which 
moves throughout the memory buffer under command of the 
operator. The memory buffer appears logically as shown in Figure 3 
where the dashes represent characters of the source line of 
indefinite length, terminated by carriage return (<cr>) and line feed 
(<1f>) characters, and ^represents the imaginary character 
pointer. Note that the CP is always located ahead of the first 
character of the first line, behind the last character of the last 
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line, or between two characters. The current line CL is the source 
line which contains the CP. 



Memory Buffer Operation 



Upon initiation of ED, the memory buffer is empty (i.e., CP is both 
ahead and behind the first and last character). The operator may 
either append lines (A command) from the source file, or enter the 
lines directly from the console with the insert command 

Kcr> 

ED then accepts any number of input lines, where each line 
terminates with a <cr> (the <lf> is supplied automatically), until a 
control-z (denoted by ~]z) is typed by the operator. The CP is 
positioned after the last character entered. The sequence 

Kcr> 

NOW IS THE<cr> 

TIME FOR<cr> 

ALL GOOD MEN<cr> 

Tz 

leaves the memory buffer as shown below 

NOW ISTHE<crxlf> 

TIME FOR<crxlf> 

ALL GOOD MEN<cr> <lf>^ 

Various commands can then be issued which manipulate the CP or 
display source text in the vicinity of the CP. The commands 
shown below with a preceding n indicate that an optional unsigned 
value can be specified. When preceded by =, the command can 
be unsigned, or have an optional preceding plus or minus sign. As 
before, the pound sign (#) is replaced by 65535. If an integer n is 
optional, but not supplied, then n=1 is assumed. Finally, if a plus 
sign is optional, but none is specified, then + is assumed. 
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± B <cr> move CP to beginning of memory buffer if 
+, and to bottom if -. 

± nC<cr> move CP by ± n characters (toward front of 
buffer if +), counting the <cr > <lf> as two 
distinct characters. 

± nD<cr> delete n characters ahead of CP if plus and 
behind CP if minus. 

±nK<cr> kill (i.e., remove) ±n lines of source text 
using CP as the current reference. If CP is 
not at the beginning of the current line when 
K is issued, then the characters before 
CP remain if + is specified, while the 
characters after CP remain if - is given in 
the command. 

± nL<cr> if n = 0, move CP to the beginning of 

the current line (if it is not already there). 
If n^O, first move the CP to the beginning 
of the current line, and then move it to the 
beginning of the line which is n lines down 
(if +) or up (if -). The CP will stop at the 
top or bottom of the memory buffer if too 
large a value is specified. 

± nT<cr> If n = then type the contents of the 

current line up to CP. If n = 1 then type the 
contents of the current line from CP to the 
end of the line. If n>1 then type the 
current line along with n-1 lines which 
follow, if + is specified. Similarly, if n>1 and 
- is given, type the previous n lines, up to 
the CP. The Break key can be depressed to 
abort long type-outs. 

±n<cr> equivalent to ±nLT, which moves up or down 
and types a single line. 
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Command Strings 



Any number of commands can be typed contiguously (up to the 
capacity of the CP/M console buffer), and are executed only 
after the <cr> is typed. Thus, the operator may use the CP/M 
console command functions to manipulate the input command. 

Rubout remove the last character 

Control-X delete the entire line 

Control-C re-initialize the CP/M System 

Control-E return carriage for long lines without trans- 
mitting buffer (max 128 chars) 

Suppose the memory buffer contains the characters shown in the 
previous section, with the CP following the last character of the 
buffer. The command strings shown below produce the results 
shown to the right. 



Command 
String 



Effect 



Resulting Memory Buffer 



B2T<cr> move to beginning of 
buffer and type 2 lines: 
"NOW IS THE 
TIME FOR" 

5C0T<cr> move CP 5 characters 
and type the beginning 
of the line "NOW I" 

2L-T<cr> move two lines down 
and type previous line 
"TIME FOR" 

-L#K<cr> move up one line, 
delete 65535 lines 
which follow 



a NOW ISTHE<cr><lf> 
TIME FOR<cr><lf> 
ALL GOOD MEN<cr> <lf> 



NOW I *STHE<crx|f> 



NOW ISTHE<cr><lf> 
TIME FOR<crx|f> 
a ALL GOOD M EN<cr> <lf> 

NOW ISTHE<crx|f>A 
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Command 



String 


Effect 


Resulting Memory Buffer 


Kcr> 

TIME TO<cr> 
INSERT<cr> 

Tz 


insert two lines 
of text 


NOW IS THE<crxlf> 

TIMETO<crx|f> 

INSERT<crx|f>A 


2L-T cr 


move up two lines, and 
type 65535 lines ahead 
of CP "NOW IS THE" 


NOWISTHE<cr><lf>A 
TIME TO cr If 
INSERT cr If 


<cr> 


move down one line 
and type one line 
"INSERT" 


NOW ISTHE<cr><lf> 

TIMETO<crx|f>A 

INSERT<crxlf> 



Text Search and Alteration 



ED also has a command which locates strings within the memory 
buffer. The command takes the form 

nF c,c 2 . . . c k 

where ^ through c k represent the characters to match 
followed by either a <cr> or control-z.* ED starts at the current 
position of CP and attempts to match all k characters. The match 
is attempted n times, and if successful, the CP is moved directly 
after the character c k . If the n matches are not successful, the 
CP is not moved from its initial position. Search strings can include 
Tl (control-l), which is replaced by the pair of symbols <cr> <lf>. 




*The control-z is used if additional commands will be typed following the "z. 
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The following commands illustrate the use of the F command: 
Command 



String 


Effect 


Resulting Memory Buffer 


B#T<cr> 


move to beginning 
and type entire 
buffer 


a NOW ISTHE<crxlf> 
TIME FOR<crxlf> 
ALL GOOD MEN<crxlf> 


FS T<cr> 


find the end of 
the string "S T" 


NOW ISTA p HE<cr><lf> 


FITzOTT 


find the next "I" and 
type to the CP then 
type the remainder of 
the current line: 
"TIME FOR" 


NOW ISTHE<crxlf> 
TIAME FOR<crxlf> 
ALL GOOD MEN<cr> <lf> 



An abbreviated form of the insert command is also allowed, 
which is often used in conjunction with the F command to make 
simple textural changes. The form is: 

I c,c 2 . . . c n Tz or 
I c-,c 2 . . . c n <cr> 

where ^ through c n are characters to insert. If the insertion 
string is terminated by a Tz, the characters through 
c n are inserted directly following the CP, and the CP is moved 
directly after character c n . The action is the same if the command 
is followed by a <cr> except that a <cr> <lf> is automatically 
inserted into the text following character c n . Consider the following 
command sequences as examples of the F and I commands: 
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Command 

String Effect Resulting Memory Buffer 

BITHIS IS tz<cr> 

Insert "THIS IS" THISISftNOWTHE<cr><lf> 

at the beginning TIME FOR<crxlf> 

of the text ALL GOOD MEN<cr><lf> 

FTIMETz-4DIPLACETz<cr> THIS IS NOWTHE<cr> <lf> 

find "TIME" and delete PLACE^FOR<cr><lf> 
it; then insert "PLACE" ALL GOOD MEN<cr> <lf> 

3FOTz-3D5DICHANGEST<cr> THIS IS NOWTHE<cr> <lf> 

find third occurrence of PLACE FOR<cr> <lf> 
"O" (i.e., the second "O" ALL CHANGES±<cr> <lf> 
in GOOD), delete pre- 
vious 3 characters; then 
insert "CHANGES" 

-8CISOURCE<cr> 

move back 8 characters THIS IS NOWTHE<cr><lf> 
and insert the line PLACE FOR<cr> <lf> 
"SOURCE<cr> <lf>" ALL SOURCE<cr> <lf> 

A p CHANGES<crxlf> 

ED also provides a single command which combines the F and I 
commands to perform simple string substitutions. The command 
takes the form 

J <cr> ( 

nSc,c 2 . . . cjzd^ . . . d m j Tz f 

and has exactly the same effect as applying the command string 

F dc 2 . . . c k Tz— kDld 1 d 2 . ■ • d m j 

a total of n times. That is, ED searches the memory buffer starting 
at the current position of CP and successively substitutes the 
second string for the first string until the end of buffer, or until 
the substitution has been performed n times. 
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As a convenience, a command similar to F is provided by ED which 
automatically appends and writes lines as the search proceeds. 
The form is 

n N dc 2 . . . c k 

which searches the entire source file for the nth occurrence of the 
string dc 2 . . . c k (recall that F fails if the string cannot be found in 
the current buffer). The operation of the N command is precisely 
the same as F except in the case that the string cannot be found 
within the current memory buffer. In this case, the entire memory 
contents is written (i.e., an automatic #W is issued). Input lines are 
then read until the buffer is at least half full, or the entire source 
file is exhausted. The search continues in this manner until the 
string has been found n times, or until the source file has been 
completely transferred to the temporary file. 

A final line editing function, called the juxtaposition command takes 
the form 

nJc,c 2 ...c k Tz d,d 2 . . . d m Tz e^ ... e p 

with the following action applied n times to the memory buffer: 
search from the current CP for the next occurrence of the string 
CiC 2 . . . c k . If found, insert the string d,,d 2 . . . d m> and move CP to 
follow d m . Then delete all characters following CP up to (but not 
including) the string e^, . . . e q , leaving CP directly after d m . If 
e^, . . . e q cannot be found, then no deletion is made. If the 
current line is 

±NOW IS THE TIME<cr><lf> 
Then the command 

JW TzWH ATTzT1<cr> 
results in 



<cr> 
Tz 



NOW WHAT A<cr><lf> 
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(Recall that Tl represents the pair <cr> <lf> in search and 
substitution strings.) 

It should be noted that the number of characters allowed by 
ED in the F,S,N, and J commands is limited to 100 symbols. 

Source Libraries 



ED also allows the inclusion of source libraries during the editing 
process with the R command. The form of this command is 

R f.,f 2 . . f n Tz or 
R f^ . . f n <cr> 

where f^ . . f n is the name of a source file on the disk with an 
assumed filetype of LIBIED reads the specified file, and places 
the characters into the memory buffer after CP, in a manner 
similar to the I command. Thus, if the command 

RMACRO<cr> 

is issued by the operator, ED reads from the file MACRO. LIB 
until the end-of-file, and automatically inserts the characters into 
the memory buffer. 

Repetitive Command Execution 



The macro command M allows the ED user to group ED commands 
together for repeated evaluation. The M command takes the form: 

n M dc 2 . . . c k 

where c^c 2 . . . c k represent a string of ED commands, not including 
another M command. ED executes the command string n times 
if n>1 . If n=0 or 1 , the command string is executed repetitively until 
an error condition is encountered (e.g., the end of the memory 
buffer is reached with an F command). 



<cr> 
tz 
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As an example, the following macro changes all occurrences of 
GAMMA to DELTA within the current buffer, and types each line 
which is changed: 

MFGAMMATz— 5DIDE LTATzOTKc r> 

or equivalently 

MSGAMMATzDELTATzOTT<cr> 

ED Error Conditions 



On error conditions, ED prints the last character read before the 
error, along with an error indicator: 

? unrecognized command 

> memory buffer full (use one of the 

commands D, K, N, S, or W to remove 
characters), F, N, or S strings too long. 

# cannot apply command the number of times 

specified (e.g., in F command) 

O cannot open LIB file in R command 

Cyclic redundancy check (CRC) information is written with each 
output record under CP/M in order to detect errors on subsequent 
read operations. If a CRC error is detected, CP/M will type 

PERM ERR DISK d 

where d is the currently selected drive (A, B ). The operator 

can choose to ignore the error by typing any character at the 
console (in this case, the memory buffer data should be examined 
to see if it was incorrectly read), or the user can reset the 
system and reclaim the backup file, if it exists. The file can 
be reclaimed by first typing the contents of the BAK file to 
ensure that it contains the proper information. 



TYPE x.BAK<cr> 
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where x is the file being edited. Then remove the primary file: 

ERA x.y<cr> 
and rename the BAK file: 

REN x.y=x.BAK<cr> 
The file can then be re-edited, starting with the previous system. 

Summary of Control Characters 

The following table summarizes the Control characters and 
commands available in ED: 



Control Character 


Function 


Tc 


system reboot 


Te 


physical <cr><lf> (not actually 




entered in command) 


Ti 


logical tab (cols 1,8, 15 ) 


Tl 


logical <cr> <lf> in search 




and substitute strings 


Tx 


line delete 


Tz 


string terminator 


rubout 


character delete 


break 


discontinue command 




(e.g., stop typing) 
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Summary of ED Commands 



Command 


Function 


nA 


dppcllU llllfco 


-+- p 


hanin hnttofn r\f hi iffor 
ut?yiii UULLUill Ul UUIIfcM 


-+- 


move cndrdcit?! pobiuons 


^ nu 


aeieit? C/iidrduLerb 




onrl prlit anrl pIhqp filpQ 




(normal end) 


nF 


find string 


H 


end edit, close and reopen files 


I 


insert characters 


ri I 

nj 


place sinnyb in juxidpobiuon 


— nr\ 


KIM llllco 


-+- ' 1 1 
± ni_ 


move aown/up nricb 


nivi 


niduiu UciiniLiuii 


nM 

ni\i 


IIIIU llfcJXl UOL/UI I t?l Willi 




autoscan 





return to original file 


-nP 


move and print pages 


U 


qui! wnn no nit; cridnyeb 


D 

n 


redo iiurdry iiic 


no 


o i i hcti ti ito ctrinnc 
bUUbLllULo blllliyb 


+ nT 
— Ill 


t\/np linp^ 


-u 


translate lower to upper case 




if U, no translation if -U 


nW 


write lines 


nZ 


sleep 


±n<cr> 


move and type (±nl_T) 
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ED Text Editing Commands 



The ED context editor contains a number of commands which 
enhance its usefulness in text editing. The improvements are found 
in the addition of line numbers, free space interrogation, and 
improved error reporting. 

The context editor issued with CP/M produces absolute line number 
prefixes when the "V" (Verify Line Numbers) command is issued. 
Following the V command, the line number is displayed ahead of 
each line in the format: 

nnnnn: 

where nnnnn is an absolute line number in the range 1 to 65535. 
If the memory buffer is empty, or if the current line is at the end 
of the memory buffer, then nnnnn appears as 5 blanks. 

The user may reference an absolute line number by preceding any 
command by a number followed by a colon, in the same format 
as the line number display. In this case, the ED program moves 
the current line reference to the absolute line number, if the 
line exists in the current memory buffer. Thus the command 

345:T 

is interpreted as "move to absolute line 345, and type the line." 
Note that absolute line numbers are produced only during the 
editing process, and are not recorded with the file. In particular, 
the line numbers will change following a deleted or expanded 
section of text. 

The user may also reference an absolute line number as a 
backward or forward distance from the current line by preceding 
the absolute line number by a colon. Thus, the command 

:400T 

is interpreted as "type from the current line number through the 
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line whose absolute number is 400.'' Combining the two line 
reference forms, the command 

345::400T 

for example, is interpreted as "move to absolute line 345, then 
type through absolute line 400." Note that absolute line 
references of this sort can precede any of the standard ED 
commands. 

A special case of the V command, "OV," prints the memory 
buffer statistics in the form: 

free/total 

where "free" is the number of free bytes in the memory buffer 
(in decimal), and "total'' is the size of the memory buffer. 

ED also includes a "block move" facility implemented through 
the "X" (Xfer) command. The form 

nX 

transfers the next n lines from the current line to a temporary 
file called 

X$$$$$$$.LIB 

which is active only during the editing process. In general, 
the user can reposition the current line reference to any portion 
of the source file and transfer lines to the temporary file. The 
transferred lines accumulate one after another in this file, and can 
be retrieved by simply typing: 

R 

which is the trivial case of the library read command. In this 
case, the entire transferred set of lines is read into the memory 
buffer. Note that the X command does not remove the transferred 
lines from the memory buffer, although a K command can be used 
directly after the X, and the R command does not empty the 
transferred line file. That is, given that a set of lines has been 
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transferred with the X command, they can be re-read any number 
of times back into the source file. The command 

OX 

is provided, however, to empty the transferred line file. 

Note that upon normal completion of the ED program through 
Q or E, the temporary LIB file is removed. If ED is aborted through 
Control-C, the LIB file will exist if lines have been transferred, 
but will generally be empty (a subsequent ED invocation will erase 
the temporary file). 

Due to common typographical errors, ED requires several 
potentially disastrous commands to be typed as single letters, 
rather than in composite commands. The commands 

E (end), H (head), O (original), Q (quit) 
must be typed as single letter commands. 
ED also prints error messages in the form 

BREAK "x" ATc 

where x is the error character, and c is the command where the 
error occurred. 
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4 

CP INI Assembler 



Introduction 



The CP/M assembler reads assembly language source files from 
the diskette, and produces 8080 machine language in Intel hex 
format. The CP/M assembler is initiated by typing 

ASM filename 

or 

ASM filename. parms 

In both cases, the assembler assumes there is a file on the diskette 
with the name 

filename. ASM 

which contains an 8080 assembly language source file. The first 
and second forms shown above differ only in that the second form 
allows parameters to be passed to the assembler to control 
source file access and hex and print file destinations. 

In either case, the CP/M assembler loads, and prints the message 

CP/M ASSEMBLER VER n.n 

where n.n is the current version number. In the case of the first 
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command, the assembler reads the source file with assumed file 
type "ASM" and creates two output files. 

filename. HEX 

and 

filename. PRN 



The "HEX" file contains the machine code corresponding to the 
original program in Intel hex format, and the "PRN" file contains 
an annotated listing showing generated machine code, error flags, 
and source lines. If errors occur during translation, they will be 
listed in the PRN file as well as at the console. 



The second command form can be used to redirect input and 
output files from their defaults. In this case, the "parms" portion 
of the command is a three letter group which specifies the origin of 
the source file, the destination of the hex file, and the destination 
of the print file. The form is 



filename. p1p2p3 



where p1 , p2, and p3 are single letters 



p1 : A,B, Y designates the disk name which contains 
the source file 

p2: A,B, Y designates the disk name which will 
receive the hex file 
Z skips the generation of the hex file 

p3: A,B Y designates the disk name which will 

receive the print file 
X places the listing at the console 

Z skips generation of the print file 



Thus, the command 
ASM X.AAA 



indicates that the source file (X.ASM) is to be taken from disk A, 
and that the hex (X.HEX) and the print (X.PRN) files are to be 
created also on disk A. This form of the command is implied if 
the assembler is run from disk A. That is, given that the operator is 
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currently addressing disk A, the above command is equivalent to 

ASM X 
The command 

ASM X.ABX 

indicates that the source file is to be taken from disk A, the hex 
file is placed on disk B, and the listing file is to be sent to the 
console. The command 

ASM X.BZZ 

takes the source file from disk B, and skips the generation of the 
hex and print files. (This command is useful for fast execution of 
the assembler to check program syntax.) 

The source program format is compatible with both the Intel 
8080 assembler (macros are not currently implemented in the 
CP/M assembler, however) as well as the Processor Technology 
Software Package #1 assembler. That is, the CP/M assembler 
accepts source programs written in either format. There are 
certain extensions in the CP/M assembler which make it somewhat 
easier to use. These extensions are described below. 



Program Format 



An assembly language program acceptable as input to the 
assembler consists of a sequence of statements of the form 

line # label operation operand ;comment 

where any or all of the fields may be present in a particular 
instance. Each assembly language statement is terminated with 
a carriage return and line feed (the line feed is inserted automatically 
by the ED program), or with the character"!" which is treated as 
an end-of-line by the assembler (thus, multiple assembly language 
statements can be written on the same physical line if separated 
by exclamation symbols). 
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The line# is an optional decimal integer value representing the 
source program line number, which is allowed on any source line 
to maintain compatibility with the Processor Technology format. In 
general, these line numbers will be inserted if a line-oriented 
editor is used to construct the original program, and thus ASM 
ignores this field if present. 

The label field takes the form 

identifier 

or 

identifier: 

and is optional, except where noted in particular statement 
types. The identifier is a sequence of alphanumeric characters 
(alphabetics and numbers), where the first character is alphabetic. 
Identifiers can be freely used by the programmer to label elements 
such as program steps and assembler directives, but cannot 
exceed 16 characters in length. All characters are significant in an 
identifier, except for the embedded dollar symbol ($) which can 
be used to improve readability of the name. Further, all lower case 
alphabetics are treated as if they were upper case. Note that the 
":" following the identifier in a label is optional. Thus, the 
following are all valid instances of labels 

x xy long$name 

x : y x 1 : longer$named$data: 

X1Y2 X 1 x2 x234$5678$9012$3456: 

The operation field contains either an assembler directive, or 
pseudo operation, or an 8080 machine operation code. The 
pseudo operations and machine operation codes are described 
below. 

The operand field of the statement, in general, contains an 
expression formed out of constants and labels, along with arithmetic 
and logical operations on these elements. Again, the complete 
details of properly formed expressions are given below. 

The comment field contains arbitrary characters following the ";" 
symbol until the next real or logical end-of-line. These characters 
are read, listed, and otherwise ignored by the assembler. In order 
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to maintain compatibility with the Processor Technology assembler, 
the CP/M assembler also treats statements which begin with a 
"*" in column one as comment statements, which are listed and 
ignored in the assembly process. Note that the Processor 
Technology assembler has the side effect in its operation of ignoring 
the characters after the operand field has been scanned. This 
causes an ambiguous situation when attempting to be compatible 
with Intel's language, since arbitrary expressions are allowed in 
this case. Hence, programs which use this side effect to introduce 
comments, must be edited to place a ";" before these fields in 
order to assemble correctly. 

The assembly language program is formulated as a sequence of 
statements of the above form, terminated optionally by an END 
statement. All statements following the END are ignored by the 
assembler. 

Forming the Operand 



In order to completely describe the operation codes and pseudo 
operations, it is necessary to first present the form of the operand 
field, since it is used in nearly all statements. Expressions in the 
operand field consist of simple operands (labels, constants, and 
reserved words), combined in properly formed subexpressions 
by arithmetic and logical operators. The expression computation is 
carried out by the assembler as the assembly proceeds. Each 
expression must produce a 1 6-bit value during the assembly. 
Further, the number of significant digits in the result must not 
exceed the intended use. That is, if an expression is to be used in a 
byte move immediate instruction, then the most significant 8 bits 
of the expression must be zero. The restrictions on the expression 
significance are given with the individual instructions. 

Labels 

As discussed above, a label is an identifier which occurs on a 
particular statement. In general, the label is given a value determined 
by the type of statement which it precedes. If the label occurs on a 
statement which generates machine code or reserves memory 
space (e.g., a MOV instruction, or a DS pseudo operation), then the 
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label is given the value of the program address which it labels. If 
the label precedes an EQU or SET, then the label is given the value 
which results from evaluating the operand field. Except for the 
SET statement, an identifier can label only one statement. 

When a label appears in the operand field, its value is substituted 
by the assembler. This value can then be combined with other 
operands and operators to form the operand field for a particular 
instruction. 

Numeric Constants 

A numeric constant is a 16-bit value in one of several bases. The 
base, called the radix of the constant, is denoted by a trailing radix 
indicator. The radix indicators are 



B binary constant (base 2) 

octal constant (base 8) 

Q octal constant (base 8) 

D decimal constant (base 10) 

H hexadecimal constant (base 16) 



Q is an alternate radix indicator for octal numbers since the letter O 
is easily confused with the digit 0. Any numeric constant which 
does not terminate with a radix indicator is assumed to be a 
decimal constant. 

A constant is thus composed as a sequence of digits, followed by 
an optional radix indicator, where the digits are in the appropriate 
range for the radix. That is binary constants must be composed 
of and 1 digits, octal constants can contain digits in the range 
0—7, while decimal constants contain decimal digits. Hexadecimal 
constants contain decimal digits as well as hexadecimal digits A 
(10D), B (1 1D), C (12D), D (13D), E (14D), and F (15D). Note that 
the leading digit of a hexadecimal constant must be a decimal digit 
in order to avoid confusing a hexadecimal constant with an 
identifier (a leading will always suffice). A constant composed in 
this manner must evaluate to a binary number which can be 
contained within a 16-bit counter, otherwise it is truncated on the 
right by the assembler. Similar to identifiers, imbedded "$" are 
allowed within constants to improve their readability. Finally, the 
radix indicator is translated to upper case if a lower case letter is 
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encountered. The following are all valid instances of numeric 
constants 

1234 1234D 1100B 1 111 $0000$ 111 1 $0000B 
1234H OFFEH 33770 33$77$22Q 
33770 0fe3h 1234d Offffh 

Reserved Words 

There are several reserved character sequences which have 
predefined meanings in the operand field of a statement. The 
names of 8080 registers are given below, which, when encountered, 
produce the value shown to the right. 



A 


7 


B 





C 


1 


D 


2 


E 


3 


H 


4 


L 


5 


M 


6 


SP 


6 


PSW 


6 



(Again, lower case names have the same values as their upper case 
equivalents.) Machine instructions can also be used in the 
operand field, and evaluate to their internal codes. In the case of 
instructions which require operands, where the specific operand 
becomes a part of the binary bit pattern of the instruction (e.g., 
MOV A,B), the value of the instruction (in this case MOV) is the 
bit pattern of the instruction with zeroes in the optional fields (e.g., 
MOV produces 40H). 

When the symbol "$" occurs in the operand field (not imbedded 
within identifiers and numeric constants) its value becomes the 
address of the text instruction to generate, not including the 
instruction contained within the current logical line. 
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String Constants 

String constants represent sequences of ASCII characters, and are 
represented by enclosing the characters within apostrophe 
symbols ('). All strings must be fully contained within the current 
physical line (thus allowing "!" symbols within strings), and must 
not exceed 64 characters in length. The apostrophe character itself 
can be included within a string by representing it as a double 
apostrophe (the keystrokes"), which becomes a single apostrophe 
when read by the assembler. In most cases, the string length is 
restricted to either one or two characters (the DB pseudo operation 
is an exception), in which case the string becomes an 8 or 16 bit 
value, respectively. Two character strings become a 16-bit constant, 
with the second character as the low order byte, and the first 
character as the high order byte. 

The value of a character is its corresponding ASCII code. There is 
no case translation within strings, and thus both upper and lower 
case characters can be represented. Note however, that only 
graphic (printing) ASCII characters are allowed within strings. 
Valid strings are 

A AB' ab' 'c' 

'a'" 

Walla Walla Wash.' 
She said "Hello" to me.' 
I said "Hello" to her.' 

Arithmetic and Logical Operators 

The operands described above can be combined in normal algebraic 
notation using any combination of properly formed operands, 
operators, and parenthesized expressions. 

The operators recognized in the operand field are 

a+b unsigned arithmetic sum of a and b 

a-b unsigned arithmetic difference between 

a and b 
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+b unary plus (produces b) 

b unary minus (identical to — b) 

a * b unsigned magnitude multiplication of a and b 

a / b unsigned magnitude division of a by b 

a MOD b remainder after a / b 
NOT b logical inverse of b (all O's become 1 s, 1 s 

become O's), where b is considered a 

16-bit value 
a AND b bit-by-bit logical and of a and b 
aORb bit-by-bit logical or of a and b 
a XOR b bit-by-bit logical exclusive or of a and b 
a SHL b the value which results from shifting a to the 

left by an amount b, with zero fill 
a SHR b the value which results from shifting a to 

the right by an amount b, with zero fill 

In each case, a and b represent simple operands (labels, numeric 
constants, reserved words, and one or two character strings), or 
fully enclosed parenthesized subexpressions such as 

10+20 10h+37Q L1/3 (L2M)SHR3 

('a' and 5fh) + 0' ( B'-B) OR (PSW+M) 

(1-(2+c))shr(A-(B+1)) 

Note that all computations are performed at assembly time as 
16-bit unsigned operations. Thus, -1 is computed as 0-1 which 
results in the value Offffh (i.e., all 1 s). The resulting expression 
must fit the operation code in which it is used. If, for example, the 
expression is used in a ADI (add immediate) instructions, then 
the high order eight bits of the expression must be zero. As a 
result, the operation "ADI — 1 " produces an error message (-1 
becomes Offffh which cannot be represented as an 8 bit value), 
while "ADI (-1 ) AND OFFH" is accepted by the assembler since 
the "AND" operation zeroes the high order bits of the expression. 
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Precedence of Operators 

As a convenience to the programmer, ASM assumes that operators 
have a relative precedence of application which allows the 
programmer to write expressions without nested levels of 
parentheses. The resulting expression has assumed parentheses 
which are defined by the relative precedence. The order of 
application of operators in unparenthesized expressions is listed 
below. Operators listed first have highest precedence (they are 
applied first in an unparenthesized expression), while operators 
listed last have lowest precedence. Operators listed on the same 
line have equal precedence, and are applied from left to right as 
they are encountered in an expression 

* / MOD SHL SHR 

NOT 
AND 
OR XOR 

Thus, the expressions shown to the left below are interpreted by 
the assembler as the fully parenthesized expressions shown to the 
right below 

a*b fc (a * b) + c 

a + b * c a + (b * c) 

a MOD b * c SHL d ((a MOD b) * c) SHL d 

a OR b AND NOT c + d SHL e a OR (b AND (NOT (c + (d SHL e)))) 

Balanced parenthesized subexpressions can always be used to 
override the assumed parentheses, and thus the last expression 
above could be rewritten to force application of operators in a 
different order as 

(a OR b) AND (NOT c) + d SHL e 

resulting in the assumed parentheses 

(a OR b) AND ((NOT c) + (d SHL e)) 

Note that an unparenthesized expression is well-formed only if 
the expression which results from inserting the assumed 
parentheses is well-formed. 
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Assembler Directives 



Assembler directives are used to set labels to specific values 
during the assembly, perform conditional assembly, define storage 
areas, and specify starting addresses in the program. Each assembler 
directive is denoted by a "pseudo operation" which appears in 
the operation field of the line. The acceptable pseudo operations 
are 



ORG 


set the program or data origin 


END 


end program, optional start address 


EQU 


numeric "equate" 


SET 


numeric "set" 


IF 


begin conditional assembly 


ENDIF 


end of conditional assembly 


DB 


define data bytes 


DW 


define data words 


DS 


define data storage area 



The ORG Directive 

The ORG statement takes the form 

label ORG expression 

where "label" is an optional program label, and expression is a 
16-bit expression, consisting of operands which are defined 
previous to the ORG statement. The assembler begins machine 
code generation at the location specified in the expression. 
There can be any number of ORG statements within a particular 
program, and there are no checks to ensure that the programmer 
is not defining overlapping memory areas. Note that most programs 
written for the CP/M system begin with an ORG statement of the 
form 

ORG 100H 

which causes machine code generation to begin at the base of the 
CP/M transient program area. If a label is specified in the ORG 
statement, then the label is given the value of the expression (this 
label can then be used in the operand field of other statements 
to represent this expression). 
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The END Directive 

The END statement is optional in an assembly language program, 
but if it is present it must be the last statement (all subsequent 
statements are ignored in the assembly). The two forms of the END 
directive are 

label END 

label END expression 

where the label is again optional. If the first form is used, the 
assembly process stops, and the default starting address of the 
program is taken as 0000. Otherwise, the expression is evaluated, 
and becomes the program starting address (this starting address 
is included in the last record of the Intel formatted machine code 
"hex" file which results from the assembly). Thus, most CP/M 
assembly language programs end with the statement 

END 100H 

resulting in the default starting address of 100H (beginning of the 
transient program area). 

The EQU Directive 

The EQU (equate) statement is used to set up synonyms for 
particular numeric values. The form is 

label EQU expression 

where the label must be present, and must not label any other 
statement. The assembler evaluates the expression, and assigns 
this value to the identifier given in the label field. The identifier is 
usually a name which describes the value in a more human-oriented 
manner. Further, this name is used throughout the program to 
"parameterize" certain functions. Suppose for example, that data 
received from a Teletype appears on a particular input port, and 
data is sent to the Teletype through the next output port in 
sequence. 
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The series of equate statements could be used to define these 
ports for a particular hardware environment 

TTYBASE EQU 10H ;BASE PORT NUMBER FOR TTY 

TTYIN EQU TTYBASE ; TTY DATA IN 
TTYOUT EQU TTYBASE + 1 ;TTY DATA OUT 

At a later point in the program, the statements which access the 
Teletype could appear as 

IN TTYIN ;READTTY DATA TO REG-A 

OUT TTYOUT ;WRITE DATA TO TTY FROM REG-A 

making the program more readable than if the absolute I/O ports 
had been used. Further, if the hardware environment is redefined 
to start the Teletype communications ports at 7FH instead of 10H, 
the first statement need only be changed to 

TTYBASE EQU 7FH ;BASE PORT NUMBER FOR TTY 

and the program can be reassembled without changing any other 
statement. 

The SET Directive 

The SET statement is similar to the EQU, taking the form 

label SET expression 

except that the label can occur on other SET statements within 
the program. The expression is evaluated and becomes the current 
value associated with the label. Thus, the EQU statement defines 
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a label with a single value, while the SET statement defines a value 
which is valid from the current SET statement to the point where 
the label occurs on the next SET statement. The use of the SET is 
similar to the EQU statement, but is used most often in controlling 
conditional assembly. 

The IF and ENDIF Directives 

The IF and ENDIF statements define a range of assembly language 
statements which are to be included or excluded during the 
assembly process. The form is 

IF expression 
statement #1 
statement #2 

statement #n 
ENDIF 

Upon encountering the IF statement, the assembler evaluates 
the expression following the IF (all operands in the expression 
must be defined ahead of the IF statement). If the expression 
evaluates to a non-zero value, then statement #1 through statement 
#n are assembled; if the expression evaluates to zero, then the 
statements are listed but not assembled. Conditional assembly is 
often used to write a single "generic" program which includes a 
number of possible run-time environments, with only a few specific 
portions of the program selected for any particular assembly. The 
following program segments for example, might be part of a program 
which communicates with either a Teletype or a CRT console 
(but not both) by selecting a particular value for TTY before the 
assembly begins. 
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TRUE 


EQU 


OFFFFH 


;DEFINE VALUE OF TRUE 


FALSE 


EQU 


NOT TRUE 


;DEFINE VALUE OF FALSE 


TTY 


EQU 


TRUE 


;TRUE IF TTY, FALSE IF CRT 


TTYBASE 


EQU 


10H 


;BASE OF TTY I/O PORTS 


CRTBASE 


EQU 


20H 


;BASE OF CRT I/O PORTS 




I r 


~i — r\/ 

I I Y 


;ASSEMBLE RELATIVE TO 
TTYBASE 


CONIN 


EQU 


TTYBASE 


;CONSOLE INPUT 


CONOUT 


EQU 
ENDIF 


TTYBASE+1 


;CONSOLE OUTPUT 


', 


r r- 

I r 


NOT TTY 


;ASSEMBLE RELATIVE TO 
CRTBASE 


POM i M 


tuu 


PDTDAOT 

CH 1 BAbL 


.CONSOLE INPUT 


CONOUT 


EQU 
ENDIF 


CRTBASE+1 


;CONSOLE OUTPUT 




IN 


CONIN 


;READ CONSOLE DATA 




OUT 


CONOUT 


;WRITE CONSOLE DATA 



In this case, the program would assemble for an environment 
where a Teletype is connected, based at port 10H. The statement 
defining TTY could be changed to 

TTY EQU FALSE 



and, in this case, the program would assemble for a CRT based at 
port 20H. 



CP/M Assembler 131 



The DB Directive 

The DB directive allows the programmer to define initialized 
storage areas in single precision (byte) format. The statement form 
is 

label DB e#1 , e#2, e#n 

where e#1 through e#n are either expressions which evaluate to 
8-bit values (the high order eight bits must be zero), or are ASCII 
strings of length no greater than 64 characters. There is no 
practical restriction on the number of expressions included on a 
single source line. The expressions are evaluated and placed 
sequentially into the machine code file following the last program 
address generated by the assembler. String characters are 
similarly placed into memory starting with the first character and 
ending with the last character. Strings of length greater than two 
characters cannot be used as operands in more complicated 
expressions (i.e., they must stand alone between the commas). 
Note that ASCII characters are always placed in memory with the 
parity bit reset (0). Further, recall that there is no translation from 
lower to upper case within strings. The optional label can be used 
to reference the data area throughout the remainder of the 
program. Examples of valid DB statements are 

data: DB 0,1,2,3,4,5 

DB data and 0ffh,5,377Q, 1+2+3+4 

signon: DB please type your name',cr,lf,0 

DB AB SHR8, C, DE AND7FH 

The DW Directive 

The DW statement is similar to the DB statement except double 
precision (two byte) words of storage are initialized. The form is 

label DW e#1,d#2 e#n 

where e#1 through e#n are expressions which evaluate to 16-bit 
results. Note that ASCII strings of length one or two characters are 
allowed, but strings longer than two characters disallowed. In all 
cases, the data storage is consistent with the 8080 processor: the 
least significant byte of the expression is stored first in memory, 
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followed by the most significant byte. Examples are 

doub: DW Offefh,doub t 4, signon- $,255+255 
DW a , 5, ab , 'CD , 6 shl 8 or 11b 

The DS Directive 

The DS statement is used to reserve an area of uninitialized 
memory, and takes the form 

label DS expression 

where the label is optional. The assembler begins subsequent 
code generation after the area reserved by the DS. Thus, the DS 
statement given above has exactly the same effect as the 
statement 

label: EQU $ ;LABEL VALUE IS CURRENT CODE LOCATION 
ORG $~ expression ;MOVE PAST RESERVED AREA 

Operation Codes 



Assembly language operation codes form the principal part of 
assembly language programs, and form the operation field of the 
instruction. In general, ASM accepts all the standard mnemonics 
for the Intel 8080 microcomputer, which are given in detail in the 
Intel manual 8080 Assembly Language Programming Manual. Labels 
are optional on each input line and, if included, take the value of 
the instruction address immediately before the instruction is issued. 
The individual operators are listed briefly in the following sections 
for completeness, although it is understood that the Intel manuals 
should be referenced for exact operator details. In each case, 

e3 represents a 3-bit value in the range of 0-7 which 

can be one of the predefined registers A, B, C, 
D, E, H, L, M, SP, or PSW. 

e8 represents an 8-bit value in the range 0-255 

e1 6 represents a 1 6-bit value in the range 0-65535 
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which can themselves be formed from an arbitrary combination 
of operands and operators. In some cases, the operands are 
restricted to particular values within the allowable range, such as 
the PUSH instruction. These cases will be noted as they are 
encountered. 

In the sections which follow, each operation code is listed in its 
most general form, along with a specific example, with a short 
explanation and special restrictions. 

Jumps, Calls and Returns 

The Jump, Call and Return instructions allow several different 
forms which test the condition flags set in the 8080 microcomputer 
CPU. The forms are 



JMB 


e16 


JMP 


L1 


Jump unconditionally to label 


JNZ 


e16 


JMP 


L2 


Jump on non zero condition to label 


JZ 


e16 


JMP 


100H 


Jump on zero condition to label 


JNC 


e16 


JNC 


L1+4 


Jump no carry to label 


JC 


e16 


JC 


L3 


Jump on carry to label 


JPO 


e16 


JPO 


$+8 


Jump on parity odd to label 


JPE 


e16 


JPE 


L4 


Jump on even parity to label 


JP 


e16 


JP 


GAMMA 


Jump on positive result to label 


JM 


e16 


JM 


al 


Jump on minus to label 


CALL 


e16 


CALL 


S1 


Call subroutine unconditionally 


CNZ 


e16 


CNZ 


S2 


Call subroutine if non zero flag 


CZ 


el 6 


CZ 


100H 


Call subroutine on zero flag 


CNC 


e16 


CNC 


S1 4 4 


Call subroutine if no carry set 


CC 


e16 


CC 


S3 


Call subroutine if carry set 


CPO 


e16 


CPO 


$4 8 


Call subroutine if parity odd 


CPE 


e16 


CPE 


S4 


Call subroutine if parity even 


CP 


e16 


CP 


GAMMA 


Call subroutine if positive result 
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CM e16 CM b1$c2 Call subroutine if minus flag 

RST e3 RST Programmed "restart," equivalent to 

CALL 8*e3, except one byte call 

RET Return from subroutine 

RNZ Return if non zero flag set 

RZ Return if zero flag set 

RNC Return if no carry 

RC Return if carry flag set 

RPO Return if parity is odd 

RPE Return if parity is even 

RP Return if positive result 

RM Return if minus flag is set 



Immediate Operand Instructions 

Several instructions are available which load single or double 
precision registers, or single precision memory cells, with constant 
values, along with instructions which perform immediate arithmetic 
or logical operations on the accumulator (register A). 

MVI e3,e8 MVI B,255 Move immediate data to 

register A, B, C, D, E, H, L, 
or M (memory) 

ADI e8 ADI 1 Add immediate operand to A 

without carry 

ACI e8 ACI OFFH Add immediate operand to A 

with carry 

SUIe8 SUI L + 3 Subtract from A without 

borrow (carry) 

SBIe8 SBI L AND 1 1 B Subtract from A with borrow 

(carry) 

AN I e8 ANI $ AND 7FH Logical "and" A with 

immediate data 
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XRI e8 XRI 1111$0000B "Exclusive or" A with 

immediate data 

ORI e8 ORI LAND 1 + 1 Logical "or" A with 

immediate data 

CPI e8 CPI a' Compare A with immediate 

data (same as SUI except 
register A not changed) 

LXIe3,e16 LXI B,100H Load extended immediate to 

register pair (e3 must be 
equivalent to B, D, H, or SP) 



Increment and Decrement Instructions 

Instructions are provided in the 8080 repertoire for incrementing 
or decrementing single and double precision registers. The 
instructions are 



INR e3 INR E Single precision increment 

register (e3 produces one of 
A, B, C, D, E, H, L, M) 

DCR e3 DCR A Single precision decrement 

register (e3 produces one of 
A, B, C, D, E, H, L, M) 

INX e3 INX SP Double precision increment 

register pair (e3 must be 
equivalent to B, D, H, or SP) 

DCX e3 DCX B Double precision decrement 

register pair (e3 must be 
equivalent to B, D, H, or SP) 

OUT e8 OUT 255 Send data from register A 

to port e8 
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Data Movement Instructions 

Instructions which move data from memory to the CPU and from 
CPU to memory are given below 



MOV e3,e3 MOV A,B 



LDAX e3 LDAX B 



STAX e3 STAX D 



LHLD e16 LHLD L1 



SHLD e16 SHLD L5+x 



LDA e16 LDA Gamma 



STA e16 STA X3-5 



POP e3 POP PSW 



PUSH e3 PUSH B 



IN e8 IN 



OUT e8 OUT 255 



Move data to leftmost 
element from rightmost 
element (e3 produces one of 
A, B, C, D, E, H, L, or M). 
MOV M,M is disallowed 

Load register A from 
computed address (e3 must 
produce either B or D) 

Store register A to computed 
address (e3 must produce 
either B or D) 

Load HL direct from 
location e16 (double 
precision load to H and L) 

Store HL direct to location 
e16 (double precision store 
from H and L to memory) 

Load register A from 
address e16 

Store register A into memory 
ate16 

Load register pair from 
stack, set SP (e3 must 
produce one of B, D, H, 
or PSW) 

Store register pair into stack, 
set SP (e3 must produce 
one of B, D, H, or PSW) 

Load register A with data 
from port e8 

Send data from register A 
to port e8 
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XTHL 
PCHL 
SPHL 
XCHG 



Exchange data from top of 
stack with HL 

Fill program counter with 
data from HL 

Fill stack pointer with data 
from HL 

Exchange DE pair with HL 
pair 



Arithmetic Logic Unit Operations 

Instructions which act upon the single precision accumulator to 
perform arithmetic and logic operations are 



ADD e3 ADD B 



ADC e3 ADC L 



SUB e3 SUB H 



SBB e3 SBB 2 



ANA e3 ANA 1-M 



XRA e3 XRA A 



ORA e3 ORA B 



CMP e3 CMP H 



Add register given by e3 to 
accumulator without carry 
(e3 must produce one of 
A, B, C, D, E, H, or L) 

Add register to A with carry, 
e3 as above 

Subtract reg e3 from A 
without carry, e3 is defined 
as above 

Subtract register e3 from A 
with carry, e3 defined 
as above 

Logical "and" reg with A, e3 
as above 

"Exclusive or" with A, e3 
as above 

Logical "or" with A, e3 
defined as above 

Compare register with A, e3 
as above 
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DAA 




Decimal adjust register A 
based upon last arithmetic 
logic unit operation 


CM A 




Complement the bits in 
register A 


STC 




Set the carry flag to 1 


CMC 




Complement the carry flag 


RLC 




Rotate bits left, (re)set carry 
as a side effect (high order 
A bit becomes carry) 


RRC 




Rotate bits right, (re)set 
carry as side effect (low 
order A bit becomes carry) 


RAL 




Rotate carry /A register to 
left (carry is involved in 
the rotate) 


RAR 




Rotate carry/A register to 
right (carry is involved in 
the rotate) 


DAD e3 


DAD B 


Double precision add 
register pair e3 to HL (e3 
must produce B, D, H, or SP) 



Control Instructions 

The four remaining instructions are categorized as control 
instructions, and are listed below 



H LT Halt the 8080 processor 

Dl Disable the interrupt system 

El Enable the interrupt system 

NOP No operation 
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Error Messages 



When errors occur within the assembly language program, they 
are listed as single character flags in the leftmost position of the 
source listing. The line in error is also echoed at the console so 
that the source listing need not be examined to determine if errors 
are present. The error codes are 

D Data error: element in data statement cannot be 

placed in the specified data area 

E Expression error: expression is ill-formed and 

cannot be computed at assembly time 

L Label error: label cannot appear in this context 

(may be duplicate label) 

N Not implemented: features which will appear in 

future ASM versions (e.g., macros) are recognized, 
but flagged in this version 

O Overflow: expression is too complicated (i.e., too 

many pending operators) to compute; simplify it 

P Phase error: label does not have the same value 

on two subsequent passes through the program 

R Register error: the value specified as a register is 

not compatible with the operation code 

V Value error: operand encountered in expression is 

improperly formed 
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Several error messages are printed which are due to terminal 
error conditions 



NO SOURCE FILE 
PRESENT 

NO DIRECTORY SPACE 



SOURCE FILE NAME 
ERROR 

SOURCE FILE READ 
ERROR 



OUTPUT FILE WRITE 
ERROR 

CANNOT CLOSE FILE 



The file specified in the ASM 
command does not exist on 
disk 

The disk directory is full; erase 
files which are not needed, 
and retry 

Improperly formed ASM file 
name (e.g., it is specified with 
"?" fields) 

Source file cannot be read 
properly by the assembler, 
execute a TYPE to determine 
the point of error 

Output files cannot be written 
properly, most likely cause is 
a full disk; erase and retry 

Output file cannot be closed, 
check to see if disk is write 
protected 



A Sample Session 



The following session shows interaction with the assembler and 
debugger in the development of a simple assembly language 
program. 

ASM SORT Assemble SORT.ASM 
CP/M ASSEMBLER - VER 1 
01 5C next tree address 

003H USE FACTOR % of table used 00 to FF (hexadecimal) 
END OF ASSEMBLY 



DIR SORT" 
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SORT ASM source file 

SORT BAK backup from last edit 

SORT PRN print file (contains tab characters) 

SORT HEX machine code file 

A 'TYPE SORT PRN 



Source line 



machine code 
location 

0100 v ORG 
generated machine code 

0100 214601 -^ 

0103 3601 

0105 214701 

0108 3600 



SORT PROGRAM IN CP/M ASSEMBLY LANGUAGE 
START AT THE BEGINNING OF THE TRANSIENT PROGRAM AR 
100H 



SORT 



LXI 
MVI 
LXI 
MVI 



H, SW 
M. 1 
H, I 
M, 



ADDRESS SWITCH TOGGLE 
SET TO 1 FOR FIRST ITERATION 
ADDRESS INDEX 

I = 



010A 7E 
010B FE09 
010D D21901 



COMP: 



0110 214601 
0113 7EB7C20001 



COMPARE I WITH ARRAY SIZE 
MOV A, M ; A REGISTER = I 
CPI N-1 ;CYSETIFI (N-1) 

JNC CONT ; CONTINUE IF I = (N-2) 

END OF ONE PASS THROUGH DATA 

LXI H,SW ; CHECK FOR ZERO SWITCHES 

MOV A.Mi ORA A' JNZ SORT ; END OF SORT IF SW=0 



RST7 



; GO TO THE DEBUGGER INSTEAD OF RE 



0119 5F16002148CONT: 
0121 4E792346 



0125 23 



CONTINUE THIS PASS 

ADDRESSING I, SO LOAD AV(I) INTO REGISTERS 
MOV E.A 1 MVI D.O! LXI H.AV! DAD D! DAD D 
MOV CM' MOV A,C! INX H! MOV B M 

LOW ORDER BYTE IN A AND C. HIGH ORDER BYTE IN B 



MOV H AND L TO ADDRESS AV(I 
INX H 



1) 



0126 965778239E 
012B DA3F01 



COMPARE VALUE WITH REGS CONTAINING AV(I) 

SUB M! MOV D.A! MOV A.B! INX H! SBB M : SUBTRACT 

BORROWSETIF AV(I + 1) AV(I) 

JC INCI : SKIP IF IN PROPER ORDER 



01 2E B2CA3F01 
0132 56702B5E 
0136 712B722B73 



013B 21460134 

013F 21470134C3INCI: 

0146 00 SW: 

0147 I: 

0148 050064001 EAV: 
000A = N 

01 5C ^ equate value 



CHECK FOR EQUAL VALUES 

ORA D! JZ INCI ; SKIP IF AV( I) = AV(I + 1 ) 

MOV D.M! MOV M,B! DCX H! MOV E.M 

MOV M.C! DCX H! MOV M.D! DCX H! MOV M.E 

INCREMENT SWITCH COUNT 
LXI H.SW! INR M 

INCREMENT I 

LXI H,l! INR M! JMPCOMP 

DATA DEFINITION SECTION 

DB ; RESERVE SPACE FOR SWITCH COUNT 

DS 1 ; SPACE FOR INDEX 

DW 5,100.30,50,20.7,1000,300,100,-32767 

EQU |$-AV)/2 ; COMPUTE N INSTEAD OF PRE 

END 
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A TYPE SORTHEX 



: 1 00 1 00002 14601 360 1214701 36007 E F E09D2 1 90 1 40 \ 
:100110002146017EB7C20001FF5F16002148011983 / 
:10012000194E79234623965778239EDA3F01B2CAA7 ( machine code 
:100130003F0156702B5E712B722B732146013421C7 ( inHEXtormat 
:0701 40004701 34C30A01006E \ 
:1001 4800050064001 E00320014000700E8032C01BB I 
:0401580064000180BE 
:0000000000 

A: DDT SORTHEX start debug run 

16K DDT VER 10 
NEXT PC 

81 5C 0000 default address (no address on END statement) 
-XP 



P=0000 100 change PC to 100 



— UFFFF untrace for 65535 steps 

C0Z0M0E0I0 A=00 B=0000 D=0000 H=0000 S=0100 P=0100 LXI 
— T1 trace 10, e steps 



abort with 
(~ rubout 
H,0146*0100 



COZOMOEOIO 
COZOMOEOIO 
COZOMOEOIO 
COZOMOEOIO 
COZOMOEOIO 
COZOMOEOIO 
C1Z0M1E0I0 
C1Z0M1E0I0 
C1Z0M1E0I0 
C1Z0M1E0I0 
COZOMOEOIO 
COZOMOEOIO 
COZOMOEOIO 
COZOMOEOIO 
COZOMOEOIO 
COZOMOEOIO 
-A10D 

010D JC 
0110 



A 


=01 


B 


=0000 


D 


=0000 


H 


=0146 


S 


=0100 


p= 


0100 


LXI 


1-1,0146 


A 


=01 


B 


=0000 


D 


=0000 


H 


=0146 


S 


=0100 


p= 


0103 


MVI 


M.01 


A 


=01 


B 


=0000 


D 


=0000 


H 


=0146 


S 


=0100 


p= 


0105 


LXI 


1-1,0147 


A 


=01 


B 


=0000 


D 


=0000 


H 


=0147 


S 


=0100 


p= 


0108 


MVI 


M.00 


A 


=01 


B 


=0000 


D 


=0000 


H 


=0147 


S 


=0100 


p= 


01 OA 


MOV 


A,M 


A 


=00 


B 


=0000 


D 


=0000 


H 


=0147 


S 


=0100 


p= 


010B 


CPI 


09 


A 


=00 


B 


=0000 


D 


=0000 


H 


=0147 


S 


=0100 


p= 


010D 


JNC 


0119 


A 


=00 


B 


=0000 


D 


=0000 


H 


=0147 


s 


=0100 


p= 


0110 


LXI 


1-1,0146 


A 


=00 


B 


=0000 


D 


=0000 


H 


=0146 


s 


=0100 


p= 


0113 


MOV 


A,M 


A 


=01 


B 


=0000 


D 


=0000 


H 


=0146 


s 


=0100 


p= 


0114 


ORA 


A 


A 


=01 


B 


=0000 


D 


=0000 


H 


=0146 


s 


=0100 


p= 


0115 


JNZ 


0100 


A 


=01 


B 


=0000 


D 


=0000 


H 


=0146 


s 


=0100 


p= 


0100 


LXI 


1-1,0146 


A 


=01 


B 


=0000 


D 


=0000 


H 


=0146 


s 


=0100 


p= 


0103 


MVI 


M.01 


A 


=01 


B 


=0000 


D 


=0000 


H 


=0146 


s 


=0100 


p= 


0105 


LXI 


1-1,0147 


A 


=01 


B 


=0000 


D 


=0000 


H 


=0147 


s 


=0100 


p= 


0108 


MVI 


M,00 


A 


=01 


B 


=0000 


D 


=0000 


H 


=0147 


s 


=0100 


p= 


01 OA 


MOV 


A,M*010B 



1 1 9 change to a jump on carry 



stopped at 
10BH 



-XP 



P=010B 100 reset program counter back to beginning of program 



— T10 trace execution lor 1 0H steps 



COZOMOEOIO 


A= 


00 


B 


=0000 


D 


=0000 


H 


=0147 


s 


=0100 


p= 


0100 


LXI 


H,0146 


COZOMOEOIO 


A= 


00 


B 


=0000 


D 


=0000 


H 


=0146 


s 


=0100 


p= 


0103 


MVI 


M.01 


COZOMOEOIO 


A= 


00 


B 


=0000 


D 


=0000 


H 


=0146 


s 


=0100 


p= 


0105 


LXI 


H,0147 


COZOMOEOIO 


A= 


00 


B 


=0000 


D 


=0000 


H 


=0147 


s 


= 0100 


p= 


0108 


MVI 


^ , altered instruction 


COZOMOEOIO 


A= 


00 


B 


=0000 


D 


=0000 


H 


=0147 


s 


=0100 


p= 


01 OA 


MOV 


A,M / 


COZOMOEOIO 


A= 


00 


B 


=0000 


D 


=0000 


H 


=0147 


s 


=0100 


p= 


010B 


CPI 


09 / 


C1Z0M1E0I0 


A= 


00 


B 


=0000 


D 


=0000 


H 


=0147 


s 


=0100 


p= 


010D 


JC 


0119 


C1Z0M-1E0I0 


A= 


00 


B 


=0000 


D 


=0000 


H 


=0147 


s 


=0100 


p= 


0119 


MOV 


E,A 


C1Z0M1E0I0 


A= 


00 


B 


=0000 


D 


=0000 


H 


=0147 


s 


=0100 


p= 


011A 


MVI 


D,00 


C1Z0M1E0I0 


A= 


00 


B 


=0000 


D 


=0000 


H 


=0147 


s 


=0100 


p= 


011C 


LXI 


H.0148 


C1Z0M1E0I0 


A= 


00 


B 


=0000 


D 


=0000 


H 


=0148 


s 


=0100 


p= 


01 1F 


DAD 


D 


C0ZOM1E0IO 


A= 


00 


B 


=0000 


D 


=0000 


H 


=0148 


s 


=0100 


p= 


0120 


DAD 


D 


C0ZOM1E0IO 


A= 


00 


B 


=0000 


D 


=0000 


H 


= 0148 


s 


=0100 


p= 


0121 


MOV 


CM 


C0ZOM1E0IO 


A= 


00 


B 


=0005 


D 


=0000 


H 


=0148 


s 


=0100 


p= 


0122 


MOV 


A.C 


C0ZOM1E0IO 


A= 


05 


B 


=0005 


D 


=0000 


H 


=0148 


s 


=0100 


p= 


0123 


INX 


H 


C0ZOM1E0IO 


A= 


05 


B 


=0005 


D 


=0000 


H 


=0149 


s 


=0100 


p= 


0124 


MOV 


B,M»0125 



Automatic ■ 
breakpoint 
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-L100 






0100 


LXI 


H.0146 


0103 


MVI 


M.01 


0105 


LXI 


H.0147 


0108 


MVI 


M,00 


01 OA 


MOV 


A,M 


010B 


CPI 


09 


010D 


JC 


0119 


0110 


LXI 


H.0146 


0113 


MOV 


A,M 


0114 


ORA 


A 


0115 


JNZ 


0100 


-L 






0118 


RST 


07 


0119 


MOV 


E,A 


011A 


MVI 


D,00 


011C 


LXI 


H.0148 



list some code 
from 100H 



- abort list with rubout 

-G.118 start program from current PC (0125H) and run in real time to11BH 

01 27 stopped with an external interrupt 7 from front panel (program was looping indefinitely) 
-T4 

look at looping program in trade mode^ 

A=38 B=0064 D=0006 H=0156 S=0100 P=0127 MOV D,A 

A=38 B=0064 D=3806 H=0156 S=0100 P=0128 MOV A.B 

A=00 B=0064 D=3806 H=0156 S=0100 P=0129 INX H 

A=00 B=0064 D=3806 H=0157 S=0100 P=012A SBB M«012B 



COZOMOEOIO 
COZOMOEOIO 
COZOMOEOIO 
COZOMOEOIO 
-D148 



,data is sorted, but program doesn't stop 



03 01 80 00 00 
00 00 00 00 00 



00 00 
00 00 



2 D . D 



-GO return to CP/M 

DDT SORTHEX reload the memory image 

16K DDT VER 1.0 
NEXT PC 
01 5C 0000 
-XP 



P=0000 1 00 Set PC to beginning of program 
— L10D list bad opcode 



010D JNC 0119 

0110 LXI H.0146 

— abort list with rubout 

— A1 OD assemble new opcode 

010D JC 119 
0110 

— L100 list starting section of program 

0100 LXI H,0146 

0103 MVI M.01 

0105 LXI H.0147 

0108 MVI M,00 

— abort list with rubout 

— A1 03 change "switch " initialization to 00 

0103 MVI M,0 

0105 



- " C return to CP/M with ctl-c (GO works as well) 
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SAVE 1 S0RT.COM save 1 page (256 bytes, from 100H to 1FFMH) on disk in case 

we have to reload later 

A DDT S0RT.COM restart DDT with 

saved memory image 

16K DDT VER 1.0 
NEXT PC 

0200 0100 "COM " tile always starts with address 100H 
— G run the program from PC- 100H 

*01 1 8 programmed stop (RST 7) encountered 
-D148 

data properly sorted 
0148 05 00 07 00 14 00 1E 00 

0150 32 00 64 00 64 00 2C 01 E8 03 01 80 00 00 00 00 2 D D 
0160 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 
0170 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 



- GO return to CP/M 

ED SORT. ASM make changes to original program 
ctl-Z 

*N,0"Z0TT find next ".0" 

MVI M,0 
* — up one line in text 

LXI H.I 
*— up another line 

MVI M.1 
*KT kill line and type next line 

LXI H.I 
*l insert new line 

M.O 



MVI 



H.I 



LXI 

*NJNC"ZOT 

JNC*T 

CONT 
*-2DIC"Z0LT 

JC 

*E s source from disk A 

{ hex to disk A 
ASM SORT.AAZ^ skip pm tile 



I = 

ADDRESS INDEX 
SET TO 1 FOR FIRST ITERATION 
ADDRESS INDEX 
ZERO SW 
ADDRESS INDEX 



;CONTINUE IF I = (N-2) 
CONT ; CONTINUE IF I 



= (N-2) 



CP/M ASSEMBLER - VER 1.0 

01 5C next address to assemble 
003H USE FACTOR 
END OF ASSEMBLY 



DDT SORT.HEX test program changes 

16K DDT VER 10 

NEXT PC 

01 5C 0000 

-G100 



*0118 
-D148 



- data sorted 



0148 B5 00 07 00 14 00 1E 00 

0150 32 00 64 00 64 00 2C 01 E8 03 01 80 00 00 00 00 
0160 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 



— abort with rubout 



— GO return to CP/M — program checks OK. 
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5 

CP/M Dynamic Debugging Tool 



Introduction 



The DDT program allows dynamic interactive testing and debugging 
of programs generated in the CP/M environment. The debugger 
is initiated by typing one of the following commands at the CP/M 
Console Command level 

DDT 

DDTfilename.HEX 
DDTfilename.COM 

where "filename" is the name of the program to be loaded and 
tested. In both cases, the DDT program is brought into main 
memory in the place of the Console Command Processor (refer 
to the CP/M Interface Guide for standard memory organization), 
and thus resides directly below the Basic Disk Operating System 
portion of CP/M. The BDOS starting address, which is located in 
the address field of the JMP instruction at location 5H, is altered 
to reflect the reduced Transient Program Area size. 

The second and third forms of the DDT command shown above 
perform the same actions as the first, except there is a subsequent 
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automatic load of the specified HEX or COM file. The action is 
identical to the sequence of commands 

DDT 

Ifilename.HEX or lfilename.COM 
R 

where the I and R commands set up and read the specified 
program to test. (See the explanation of the I and R commands 
below for exact details.) 

Upon initiation, DDT prints a sign-on message in the format 
DDT VER m.m 

where 

D Digital Research standard version 

M MDS version 

I IMSAI standard version 

O Omron systems 

S Digital Systems standard version 

m.m is the revision number. 

Following the sign on message, DDT prompts the operator with the 
character "-" and waits for input commands from the console. 
The operator can type any of several single characters commands, 
terminated by a carriage return to execute the command. Each 
line of input can be line-edited using the standard CP/M controls 

rubout remove the last character typed 

Control-X remove the entire line, ready for re-typing 
Control-C system reboot 

Any command can be up to 32 characters in length (an automatic 
carriage return is inserted as the 33rd character), where the first 
character determines the command type. 
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A enter assembly language mnemonics with 
operands 

D display memory in hexadecimal and ASCII 

F fill memory with constant data 

G begin execution with optional breakpoints 

I set up a standard input file control block 

L list memory using assembler mnemonics 

M move a memory segment from source to 
destination 

R read program for the subsequent testing 

S substitute memory values 

T trace program execution 

U untraced program monitoring 

X examine and optionally alter the CPU state 



The command character, in some cases, is followed by zero, one, 
two, or three hexadecimal values which are separated by commas 
or single blank characters. All DDT numeric output is in hexadecimal 
form. In all cases, the commands are not executed until the 
carriage return is typed at the end of the command. 

At any point in the debug run, the operator can stop execution of 
DDT using either a Control-C or GO (jump to location 0000H), and 
save the current memory image using a SAVE command of the 
form 

SAVE n filename.COM 

where n is the number of pages (256 byte blocks) to be saved on 
disk. The number of blocks can be determined by taking the high 
order byte of the top load address and converting this number to 
decimal. For example, if the highest address in the Transient 
Program Area is 1234H then the number of pages is 12H, or 18 
in decimal. Thus the operator could type a Control-C during the 
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debug run, returning to the Console Processor level, followed by 

SAVE 18 X.COM 

The memory image is saved as X.COM on the diskette, and can 
be directly executed by simply typing the name X. If further testing 
is required, the memory image can be recalled by typing 

DDTX.COM 

which reloads the previously saved program from location 100H 
through page 18 (12FFH). The machine state is not a part of the 
COM file, and thus the program must be restarted from the 
beginning in order to properly test it. 

DDT Commands 



The individual commands are given below in some detail. In 
each case, the operator must wait for the prompt character (-) 
before entering the command. In the explanation of each command, 
the command letter is shown in some cases with numbers 
separated by commas, where the numbers are represented by 
lower case letters. These numbers are always assumed to be in a 
hexadecimal radix, and from one to four digits in length (longer 
numbers will be automatically truncated on the right). 

Many of the commands operate upon a "CPU state" which 
corresponds to the program under test. The CPU state holds the 
registers of the program being debugged, and initially contains 
zeroes for all registers and flags except for the program counter (P) 
and stack pointer (S), which default to 100H. The program 
counter is subsequently set to the starting address given in the last 
record of a HEX file if a file of this form is loaded (see the I and R 
commands). 
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The A (Assemble) Command 



DDT allows inline assembly language to be inserted into the current 
memory image using the A command which takes the form 

As 

where s is the hexadecimal starting address for the inline 
assembly. DDT prompts the console with the address of the next 
instruction to fill, and reads the console, looking for assembly 
language mnemonics (see the Intel 8080 Assembly Language 
Reference Card for a list of mnemonics), followed by register 
references and operands in absolute hexadecimal form. Each 
successive load address is printed before reading the console. 
The A command terminates when the first empty line is input from 
the console. 

Upon completion of assembly language input, the operator can 
review the memory segment using the DDT disassembler. (See the 
L command.) 

Note that the assembler/disassembler portion of DDT can be 
overlayed by the transient program being tested, in which case the 
DDT program responds with an error condition when the A and L 
commands are used. 

The D (Display) Command 



The D command allows the operator to view the contents of 
memory in hexadecimal and ASCII formats. The forms are 

D 

Ds 

Ds,f 

In the first case, memory is displayed from the current display 
address (initially 100H), and continues for 16 display lines. Each 
display line takes the form shown below 

aaaa bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb cccccccccccccccc 
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where aaaa is the display address in hexadecimal, and bb represents 
data present in memory starting at aaaa. The ASCII characters 
starting at aaaa are given to the right (represented by the sequence 
of c's), where non-graphic characters are printed as a period (.) 
symbol. Note that both upper and lower case alphabetics are 
displayed, and thus will appear as upper case symbols on a 
console device that supports only upper case. Each display line 
gives the values of 16 bytes of data, except that the first line 
displayed is truncated so that the next line begins at an address 
which is the multiple of 16. 

The second form of the D command shown above is similar to 
the first, except that the display address is first set to address s. 
The third form causes the display to continue from address s 
through address f. In all cases, the display address is set to the first 
address not displayed in this command, so that a continuing 
display can be accomplished by issuing successive D commands 
with no explicit addresses. 

Excessively long displays can be aborted by pushing the rubout 
key. 

The F(Fill) Command 



The F command takes the form 
Fs.f.c 

where s is the starting address, f is the final address, and c is a 
hexadecimal byte constant. The effect is as follows: DDT stores the 
constant c at address s, increments the value of s and tests 
against f. If s exceeds f then the operation terminates, otherwise 
the operation is repeated. Thus, the fill command can be used to 
set a memory block to a specific constant value. 
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The G(Go) Command 



Program execution is started using the G command, with up to two 
optional breakpoint addresses. The G command takes one of the 
forms 

G 

Gs 

Gs,b 

Gs,b,c 

G,b 

G.b.c 

The first form starts execution of the program under test at the 
current value of the program counter in the current machine 
state, with no breakpoints set. The current program counter can be 
viewed by typing an X or XP command. The second form is 
similar to the first except that the program counter in the current 
machine state is set to address s before execution begins. The 
third form is the same as the second, except that program execution 
stops when address b is encountered (b must be in the area of 
the program under test). The instruction at location b is not executed 
when the breakpoint is encountered. The fourth form is identical 
to the third, except that two breakpoints are specified, one at b and 
the other at c. Encountering either breakpoint causes execution 
to stop, and both breakpoints are subsequently cleared. The last 
two forms take the program counter from the current machine 
state, and set one and two breakpoints, respectively. 

Execution continues from the starting address in real-time to the 
next breakpoint. That is, there is no intervention between the 
starting address and the break address by DDT. Thus, if the program 
under test does not reach a breakpoint, control cannot return to 
DDT. Upon encountering a breakpoint, DDT stops execution and 
types 

*d 

where d is the stop address. The machine state can be examined 
at this point using the X (Examine) command. The operator must 
specify breakpoints which differ from the program counter address 
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at the beginning of the G command. Thus, if the current program 
counter is 1234H, then the commands 

G,1234 

and 

G400,400 

both produce an immediate breakpoint, without executing any 
instructions whatsoever. 

The I (Input) Command 



The I command allows the operator to insert a file name into the 
default file control block at 5CH (the file control block created by 
CP/M for transient programs is placed at this location; see the 
CP/M Interface Guide). The default FCB can be used by the 
program under test as if it had been passed by the CP/M Console 
Processor. Note that this file name is also used by DDT for 
reading additional HEX and COM files. The form of the I command is 

Ifilename 

or 

Ifilename. filetype 

If the second form is used, and the filetype is either HEX or 
COM, then subsequent R commands can be used to read the pure 
binary or hex format machine code (see the R command for 
further details). 

The L (List) Command 



The L command is used to list assembly language mnemonics in a 
particular program region. The forms are 

L 

Ls 

Ls,f 
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The first command lists twelve lines of disassembled machine 
code from the current list address. The second form sets the list 
address to s, and then lists twelve lines of code. The last form 
lists disassembled code from s through address f. In all three cases, 
the list address is set to the next unlisted location in preparation 
for a subsequent L command. Upon encountering an execution 
breakpoint, the list address is set to the current value of the 
program confer (see the G and T commands). Again, long typeouts 
can be aborted using the rubout key during the list process. 

The M (Move) Command 



The M command allows block movement of program or data 
areas from one location to another in memory. The form is 

Ms,f,d 

where s is the start address of the move, f is the final address of the 
move, and d is the destination address. Data is first moved from s 
to d, and both addresses are incremented. If s exceeds f then the 
move operation stops, otherwise the move operation is repeated. 

The R (Read) Command 



The R command is used in conjunction with the I command to 
read COM and HEX files from the diskette into the transient 
program area in preparation for the debut run. The forms are 

R 

Rb 

where b is an optional bias address which is added to each program 
or data address as it is loaded. The load operation must not 
overwrite any of the system parameters from 000H through OFFH 
(i.e., the first page of memory). If b is omitted, then b = 0000 is 
assumed. The R command requires a previous I command, 
specifying the name of a HEX or COM file. The load address for 
each record is obtained from each individual HEX record, while 
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an assumed load address of 100H is taken for COM files. Note that 
any number of R commands can be issued following the I 
command to re-read the program under test, assuming the tested 
program does not destroy the default area at 5CH. Further, any 
file specified with the filetype "COM" is assumed to contain machine 
code in pure binary form (created with the LOAD or SAVE 
command), and all others are assumed to contain machine code in 
Intel hex format (produced, for example), with the ASM command). 

Recall that the command 

DDT filename. filetype 
which initiates the DDT program is equivalent to the commands 

DDT 

-Ifilename. filetype 
-R 

Whenever the R command is issued, DDT responds with either the 
error indicator "?" (file cannot be opened, or a checksum error 
occurred in a HEX file), or with a load message taking the form 

NEXT PC 
nnnn pppp 

where nnnn is the next address following the loaded program, 
and pppp is the assumed program counter (100H for COM files, or 
taken from the last record if a HEX file is specified). 

The S (Set) Command 



The S command allows memory locations to be examined and 
optionally altered. The form of the command is 

Ss 

where s is the hexadecimal starting address for examination and 
alteration of memory. DDT responds with a numeric prompt, 
giving the memory location, along with the data currently held in 
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the memory location. If the operator types a carriage return, then 
the data is not altered. If a byte value is typed, then the value is 
stored at the prompted address. In either Gase, DDT continues to 
prompt with successive addresses and values until either a period 
(.) is typed by the operator, or an invalid input value is detected. 

The T (Trace) Command 



The T command allows selective tracing of program execution 
for 1 to 65535 program steps. The forms are 

T 
Tn 

In the first case, the CPU state is displayed, and the next 
program step is executed. The program terminates immediately, 
with the termination address displayed as 

*hhhh 

where hhhh is the next address to execute. The display address 
(used in the D command) is set to the value of H and L, and the list 
address (used in the L command) is set to hhhh. The CPU state 
at program termination can then be examined using the X command. 

The second form of the T command is similar to the first, except 
that execution is traced for n steps (n is a hexadecimal value) 
before a program breakpoint occurs. A breakpoint can be forced in 
the trace mode by typing a rubout character. The CPU state is 
displayed before each program step is taken in trace mode. The 
format of the display is the same as described in the X command. 

Note that program tracing is discontinued at the interface to 
CP/M, and resumes after return from CP/M to the program under 
test. Thus, CP/M functions which access I/O devices, such as 
the diskette drive, run in real-time, avoiding I/O timing problems. 
Programs running in trace mode execute approximately 500 
times slower than real time since DDT gets control after each user 
instruction is executed. Interrupt processing routines can be 
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traced, but it must be noted that commands which use the breakpoint 
facility (G, T, and U) accomplish the break using a RST 7 instruction, 
which means that the tested program cannot use this interrupt 
location. Further, the trace mode always runs the tested program 
which interrupts enabled, which may cause problems if 
asynchronous interrupts are received during tracing. 

Note also that the operator should use the rubout key to get control 
back to DDT during trace, in order to ensure that the trace for the 
current instrucion is completed before interruption. 

The U (Untrace) Command 



The U command is identical to the T command except that 
intermediate program steps are not displayed. The untrace mode 
allows from 1 to 65535 (OFFFFH) steps to be executed in 
monitored mode, and is used principally to retain control of an 
executing program while it reaches steady state conditions. All 
conditions of the T command apply to the U command. 

The X (Examine) Command 



The X command allows selective display and alteration of the 
current CPU state for the program under test. The forms are 

X 
Xr 

where r is one of the 8080 CPU registers 



c 


Carry Flag 


(0/1) 


z 


Zero Flag 


(0/1) 


M 


Minus Flag 


(0/1) 


E 


Even Parity Flag 


(0/1) 


I 


Interdigit Carry 


(0/1) 


A 


Accumulator 


(0-FF) 


B 


BC register pair 


(0-FFFF 


D 


DE register pair 


(0-FFFF 
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H HL register pair (O-FFFF) 
S Stack Pointer (O-FFFF) 
P Program Counter (O-FFFF) 

In the first case, the CPU register state is displayed in the format 

CfZfMfEflf A=bb B=dddd D=dddd H-dddd S=dddd P=dddd inst 

where f is a or 1 flag value, bb is a byte value, and dddd is a 
double byte quantity corresponding to the register pair. The "inst" 
field contains the disassembled instruction which occurs at the 
location addressed by the CPU state's program counter. 

The second form allows display and optional alteration of register 
values, where r is one of the registers given above (C, Z, M, E, I, 
A, B, D, H, S, or P). In each case, the flag or register value is the 
first displayed at the console. The DDT program then accepts 
input from the console. If a carriage return is typed, then the flag or 
register value is not altered. If a value in the proper range is 
typed, then the flag or register value is altered. Note that BC, DE, 
and HL are displayed as register pairs. Thus, the operator types 
the entire register pair when B, C, or the BC pair is altered. 



Implementation Notes 



The organization of DDT allows certan non-essential portions to be 
overlayed in order to gain a larger transient program area for 
debugging large programs. The DDT program consists of two parts: 
the DDT nucleus and the assembler/disassembler module. The 
DDT nucleus is loaded over the Console Command Processor, and, 
although loaded with the DDT nucleus, the assembler/disassembler 
is overlayable unless used to assemble or disassemble. 

In particular, the BDOS address at location 6H (address field of 
the JMP instruction at location 5H) is modified by DDT to address 
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the base location of the DDT nucleus which, in turn, contains a 
JMP instruction to the BDOS. Thus, programs which use this address 
field to size memory see the logical end of memory at the base 
of the DDT nucleus rather than the base of the BDOS. 

The assembler/disassembler module resides directly below the 
DDT nucleus in the transient program area. If the A, L, T, or X 
commands are used during the debugging process then the DDT 
program again alters the address field at 6H to include this 
module, thus further reducing the logical end of memory. If a 
program loads beyond the beginning of the assembler/disassembler 
module, the A and L commands are lost (their use produces a "?" 
in response), and the trace and display (T and X) commands list the 
"inst" field of the display in hexadecimal, rather than as a decoded 
instruction. 

Sample Session 



The following example shows an edit, assemble, and debug for a 
simple program which reads a set of data values and determines 
the largest value in the set. The largest value is taken from the 
vector, and stored into "LARGE" at the termination of the program. 



ED SCAN ASM 



" - ] 


ORG 


- I 100H 




MVI 


B.LEN 




MVI 


CO 


LOOP 


POOL 


LXI 


LOOP: / 


MOV 


A.M 


rubout ' 


SUB 


C 


deletes 


JNC 


NFOUND 


.characters NEW LARGEST VALU 




MOV 


C,A 


NFOUND: 


INX 


H 




DCR 


B 




JNZ 


LOOP 



tab character .. rubout wbout echQ 

L-L^ART_OF_TRANSLENT AREA 
JJENGJH OF VECJORTO SCAN 
' LARGER— RST VALUE SO FAR 
H.VECT_ J3ASE OF VECTOR 
; GET VALUE 
J LARGER VALUE IN 
JUMP IF L A R GE RVAL U E NOT FOUND 



TO NEXT ELEMENT 
MORE TO SCAN' 
FOR ANOTHER 



END OF SCAN. STORE C 

MOV" A£ ; GET LARGEST VALUE 

STA LARGE 

JMP ; REBOOT 



Create Source 
Program - underlined 
characters typed 
by programmer. 
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V ECT: 

LEN 

LARGE: 

TZ*BOP 



T EST DATA 
DB 
EQU 
DS 
END 



2,0,4,3, 5,6,1,5 
$-VECT ; LE NGTH 
1 ; LARGEST VALUE ON EXIT 



ORG 100H 
MVI B.LEN 
MVI CO 
LXI H.VECT 

LOOP: MOV A,M 
SUB C 
JNC NFOUND 

; NEW LARGEST VALUE, 

MOV C.A 
NFOUND: INX H 
DCR B 
JNZ LOOP 

; END OF SCAN, STORE 

MOV A,C 

STA ' LARGE 
JMP 



START OF TRANSIENT AREA 
LENGTH OF VECTOR TO SCAN 
LARGEST VALUE SO FAR 
BASE OF VECTOR 
GET VALUE 
LARGER VALUE IN C? 
JUMP IF LARGER VALUE NOT FOUND 
STORE ITTOC 

TO NEXT ELEMENT 
MORE TO SCAN? 
FOR ANOTHER 

; GET LARGEST VALUE 

; REBOOT 



TEST DATA 



VECT: DB 
LEN EQU 
LARGE: DS 
END 



2,0,4,3,5,6,1,5 

$-VECT : LENGTH 

1 ; LARGEST VALUE ON EXIT 

End of Edit 



ASM SCAN c , . . 
Start Assembler 

CP/M ASSEMBLER - VER 1 .0 



0122 

002H USE FACTOR 
END OF ASSEMBLY 

TYPE SCAN , PRN 



Assembly Complete — Look at Program Listing 



Code Address/ 



0104 211901 

0107 7E 

0108 91 

0109 D20D01 



010C 4F 

010D 23 

01 OE 05 

01 OF C20701 



Source Program 



LOOP: 



ORG 
^MVI 
MVI 
LXI 
MOV 
SUB 
JNC 



100H 

B.LEN 

CO 

H, VECT. 

A.M 

C 

NFOUND 



NEW LARGEST VALUE, 
MOV C.A 
NFOUND INX H 
DCR B 



JNZ 



LOOP 



START OF TRANSIENT AREA 
LENGTH OF VECTOR TO SCAN 
LARGEST VALUE SO FAR 
BASE OF VECTOR 
GET VALUE 
LARGER VALUE IN C? 
JUMP IF LARGER VALUE NOT FOUND 
STORE ITTOC 

TO NEXT ELEMENT 
MORE TO SCAN? 
FOR ANOTHER 



0112 
0113 
0116 



79 

322101 
C30000 
Code/data listing 
truncated 



END OF SCAN. STORE C 



MOV 
STA 
JMP 

TEST DATA 



A,C 

LARGE 





; GET LARGEST VALUE 
; REBOOT 



0119 0200040305VECT: DB 

0008 = ~x LEN EQU 

0121 Value of) LARGE: DS 

0122 Equate END 



2.0,4,3,5,6,1,5 

S-VECT : LENGTH 

1 ; LARGEST VALUE ON EXIT 
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DDT SCAN HEX 

16K DDT VER 
NEXT PC 
0121 0000 
-X 



Start Debugger using hex format machine code 



1.0 



last load address + 1 



C0Z0M0E0I0 A= 
-XP 



00 



next instruction 
i to execute at 
B=0000 D=0000 H=0000 S=0100 P=0000 OUT 7F PC=0 



P=0000 
-X 



100 



Examine registers oefore debug run 
Change PC to 700 
Look at registers again 
COZOMOEOIO A=00 B=0000 D=0000 H=0000 S=0100 P= 



Disassembled Machine 
Code at 100H 
(See Source Listing 
tor comparison) 



-L100 






0100 


MVI 


B,08 


0102 


MVI 


COO 


0104 


LXI 


H,0119 


0107 


MOV 


A.M 


0108 


SUB 


C 


0109 


JNC 


010D 


01OC 


MOV 


C,A 


010D 


INX 


H 


010E 


DCR 


B 


010F 


JNZ 


0107 


01 12 


MOV 


A,C 


^[_ 






01 13 


STA 


0121 


0116 


JMP 


0000 


01 19 


STAX 


B 


011A 


NOP 




011B 


INR 


B 


011C 


INX 


B 


011D 


DCR 


B 


01 1E 


MVI 


B.01 


0120 


DCR 


B 


0121 


LXI 


D.2200 


0124 


LXI 


H.0200 


-A116 


enter inline ass 


0116 


RST7 


V 

1 


0117 


(single carriage rt 


-L113 


List Code at 1 1 


0113 


STA 


0121 


0116 


RST 


07— 


0117 


NOP 




0118 


NOP 




0119 


STAX 


B 


011A 


MOP 




011B 


NR 


B 


011C 


NX 


B 



^- PC changed 

0100 MVI B,08"~^ 
Next instruction 
to execute atPC=100 



A little more 
machine code 
(note that Program 
ends at location 1 16 
with a JMP to 0000} 



will cause the program under test to return to DDT if 1 16H 
is ever executed. 



- in place of JMP 
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— X Look at registers 

COZOMOEOIO A=00 B=0000 D=0000 
— T Execute Program for one step. 

COZOMOEOIO A=00 B=0000 D=0000 
~I Trace one step again (note 08H in B) 

COZOMOEOIO A=00 B=0000 D=OO0O 
— T Trace again (Register C is cleared) 

COZOMOEOIO A=00 B=0800 D=0000 H=0000 S=O100 P=0104 LXIH,01 19*0107 
— 13 Trace three steps 



H=0000 S=0100 P=0100 MVI B,08 
initial CPU state, before j is executed 
H=0000 S=0100 P=0100 MVI B,08«0102 

automatic breakpoint ^ 
H=0000 S=0100 P=0102 MVI C,00*0104 



COZOMOEOIO A=00 B=0800 D=0000 H=0119 S = 
COZOMOEOIO A=02 B=0800 D=0000 H=0119 S = 
C0Z0M0E0I1 A=02 B=0800 D=0000 H=0119 S = 
— D1 19 Display memory starting at 11 9H 

Program data 



0100 P=0107 MOV A,M 

0100 P=0108 SUB C 

0100 P=0109 JNC 010D*010D 

Automatic breakpoint at 10DH -J 



0119 


ff>2 


00 


04 


03 


05 


06 


00 




















slower case x-^ 


0120 




^11 


00 


22 


21 


00 


02 


7E 


EB 


77 


13 


23 


EB 


OB 




"iT 


..."/..". w.$ .© 


0130 


C2 


27 


01 


C3 


03 


29 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


0140 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 




0150 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


Data is displayed 


0160 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


in ASCII with a ,, 0" 


0170 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


in the position of 


0180 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


non-graphic 


0190 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


characters 


01 AO 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 




01B0 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 




01C0 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 




-X 






Current CPU state 























C0Z0M0E0I1 A=02 B=0800 D=0000 H=0119 
—15 Trace 5 steps from current CPU state 



S=0100 P=010D INX 



C0Z0M0E0I1 


A 


=02 


B 


=0800 


D 


=0000 


H 


=0119 


s 


=0100 


p 


=010D 


INX 


H 


C0Z0M0E0I1 


A 


=02 


B 


=0800 


D 


=0000 


H 


=011A 


s 


=0100 


p 


=010E 


DCR 


B 


C0Z0M0E0I1 


A 


=02 


B 


=0700 


D 


=0000 


H 


=011A 


s 


=0100 


p 


=010F 


JNZ 


0107 


C0Z0M0E0I1 


A 


=02 


B 


=0700 


D 


=0000 


H 


=011A 


s 


=0100 


p 


=0107 


MOV 


A.M 


C0Z0M0EOI1 


A 


=00 


B 


=0000 


D 


= 0000 


H 


=0119 


s 


=0100 


p 


=0108 


SUB 


C«0109 



Automatic 
Breakpoint 



— U5 Trace without listing intermediate states 

C0Z0M0E1I1 A=00 B=0700 D=0000 H=011A S=0100 P=0109 JNC 010D*0108 
-X CPU State at end of U5 



C0Z0M0E1I1 A=04 

-G 



B=0600 D=0000 H=011B S=0100 P=0108 SUE 



Run program from current PC until completion tin real-time) 
breakpoint at 116H. caused by executing RST 7 in machine code 



•0116 

—X CPU state at end of program 

C0Z1M0E1I1 A=00 B=0000 D=0000 H=0121 
— X.P examine and change program counter 

P=0116 100 



S=0100 P=0116 RST 07 



C0Z1M0E1I1 A=00 B=0000 D=0000 H=0121 S=0100 P=0100 MVI B.C 
-T10 Trace 10 (hexadecimal) steps subtext for comparison^ 

. first data element current largest value 




000 
0000 
D=000C 
D=«JOO 

oaSgy- d=oooo 

0800 D=0000 



H=0121 ,-8-=0100 
H=S»^C S=0100 
--Ff=0121 S = 0100 
H=0119 S=0100 
H=0119 S = 0100 
H=0119 S=0100 



P=0100 
P=0102 
P=0104 
P=0107 
P=0108 
P=0109 
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C0Z0M0E0I1 


A 


02 


B 


=0800 


D 


=0000 


H 


= 01 19 


S 


=0100 


P= 


010D 


INX 


H 


C0Z0MOEOI1 


A 


=02 


B 


= 0800 


D 


=0000 


H 


=01 1 A 


S 


=0100 


p= 


010E 


DCR 


B ^\ 


C0Z0MOE0I1 


A 


=02 


B 


= 0700 


D 


=0000 


H 


=01 1 A 


S 


=0100 


p= 


010F 


JNZ 


0107 


C0Z0M0E0I1 


A 


= 02 


B 


=0700 


D 


= 0000 


H 


= 011A 


S 


= 0100 


p= 


0107 


MOV 


A.M 


C0Z0M0E0I1 


A 


^00 


B 


=0700 


D 


=0000 


H 


=011A 


S 


= 0100 


p= 


0108 


SUB 


C 


C0Z1M0E1I1 


A 


=00 


B 


=0700 


D 


=0000 


H 


=011A 


s 


=0100 


p= 


0109 


JNC 


010D 


C0Z1M0E1I1 


A 


=00 


B 


= 0700 


D 


=0000 


H 


= 011A 


s 


=0100 


p= 


0100 


INX 


H 


C0Z1M0E1I1 


A 


=00 


B 


=0700 


D 


= 0000 


H 


=01 1 B 


s 


=0100 


p= 


010E 


DCR 


B 


C0Z0M0E1I1 


A 


=00 


B 


=0600 


D 


=0000 


H 


=011B 


s 


= 0100 


p= 


010F 


JNZ 


0107 


C0Z0M0E1I1 


A 


=00 


B 


=0600 


D 


=0000 


H 


=011B 


s 


=0100 


p= 


0107 


MOV 


A.M*0108 


-A 109 































Insert a "hot patch " into 
0109 JC_IOP the machine code 

to change the 
010C JNCtoJC 



Program should have moved the - 
value from A into C since A C. 
Since this code was not executed, 
it appears that the JNC should 
have been a JC instruction 



-GO 



Stop DDT so that a version of 

the patched program can be saved 



SAVE 1 SCAN.COM Program resides on first page, so save 1 page. 

A DD.T.SCAN. COM Restart DDT with the saved memory image to continue testing 

16K DDT VER 1.0 
NEXT PC 
0200 0100 

— L100 List some code 



0100 


MVI 


B 08 


0102 


MVI 


COO 


0104 


LXI 


H.0119 


0107 


MOV 


A.M 


0108 


SUB 


C 


0109 


JC 


010D-^ 


010C 


MOV 


C.A 


010D 


INX 


H 


010E 


DCR 


B 


010F 


JNZ 


0107 


01 12 


MOV 


A.C 


-XP 







- Previous patch is present in X-COM 



— T10 Trace to see how patched version operates 



Data is moved from A to C 



COZOMOEOIO 


A 


= 00 


B 


=0000 


D 


= 0000 


H 


= 0000 


S 


= 


00 


p 


= 0100 


MVI 


B.08 


COZOMOEOIO 


A 


= 00 


B 


=0800 


D 


= 0000 


H 


= 0000 


S 


=0 


00 


p 


= 0102 


MVI 


C 00 


COZOMOEOIO 


A 


-00 


B 


-0800 


D 


-0000 


H 


=0000 


S 





00 


p 


0104 


LXI 


H.01 19 


COZOMOEOIO 


A 


-00 


B 


0800 


D 


= 0000 


H 


J3T 1 9 


S 


-o 


00 


p 


=0107 


MOV 


A.M 


COZOMOEOIO 


A 


= @, 


B 


= 0800 


D 


=0000. 


-M 


= 0119 


S 


= 


00 


p 


=0108 


SUB 


C 


C0Z0M0E0I1 


A 


=02 




= 0800 


D 


=ooot> 


H 


= 0119 


S 


= 


00 


p 


=0109 


JC 


010D 


C0Z0M0E0I1 


A 


-02 


B 


=«£S00 


.^=0000 


H 


= 01 19 


S 





00 


p 


010C 


MOV 


C A 


C0Z0M0E0I1 


A 


02 


B 


= 08@ 


D 


- 0000 


H 


-0119 


S 





00 


p 


-010D 


INX 


H 


C0Z0M0E0I1 


A 


= 02 


B 


0802 


D 


0000 


H 


01 1A 


S 


= 


00 


p 


= 010E 


DCR 


B 


COZOMOEOM 


A 


=02 


B 


=0702 


D 


= 0000 


H 


= 01 1A 


S 


= 


00 


p 


-010F 


JNZ 


0107 


C0Z0M0E0I1 


A 


= 02 


B 


=0702 


D 


= 0000 


H 


= 01 1 A 


S 


-0 


00 


p 


0107 


MOV 


A.M 


COZOMOEOM 


A 


= 00 


B 


= 0702 


D 


= 0000 


H 


=01 1 A 


S 





00 


p 


0108 


SUB 


C 


C1Z0M1E0I0 


A 


= FE 


B 


= 0702 


D 


-oooo 


H 


-01 1 A 


S 


= 


00 


p 


= 0109 


JC 


10D 


C1Z0M1 EOIO 


A 


= FE 


B 


= 0702 


D 


^0000 


H 


= 01 1 A 


S 


=0 


00 


p 


= 010D 


[NX 


H 


C1Z0M1E0I0 


A 


= FE 


B 


= 0702 


D 


=0000 


H 


= 01 1 B 


S 





00 


p 


010E 


DCR 


B 


C1Z0M0E1I1 


A 


FE 


B 


0602 


D 


= 0000 


H 


01 1B 


S 


= 


00 


p 


= 010F 


JNZ 


0107'0107 


-X 
























breakpoint alter 16 steps 



C1Z0M0E1I1 A-FE B = 0602 D = 0000 H-011B S~0 
— G.108 Run from current PC and breakpoint at 108H 



00 P-0107 MOV AM 
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*0108 
-X 



r 



next data item 



C1Z0M0E1I1 A=04 B=0602 D=0000 H=011B S=0100 P=0108 SUB C 
~ T Single step for a few cycles 

C1Z0M0E1I1 A=04 B = 0602 D=0000 H=011B S=0100 P = 0108 SUB C-0109 
-T 

COZ0MOEOI1 A=02 B=0602 D = 0000 H=011B S = 0!00 P=0109 JC 010D-010C 
-X 

COZOM0EOI1 A=02 B=0602 D=0000 H=011B S = 0100 P=010C MOV C.A 
— G Run to completion 

"0116 
-X 

C0Z1M0E1I1 A=03 B=0003 D=0000 H=0121 S=0100 P = 0116 RST 07 

-S121 look at the value of LARGE 



0121 03 

0122 00 

0123 22 

0124 21 

0125 00 

0126 02 

0127 7E 
-L100 



Wrong Value! 



End of the S command 



0100 


MVI 


B,08 


0102 


MVI 


COO 


0104 


LXI 


H.0119 


0107 


MOV 


A,M 


0108 


SUB 


C 


0109 


JC 


010D 


010C 


MOV 


C.A 


010D 


INX 


H 


010E 


DCR 


B 


010F 


JNZ 


0107 


0112 


MOV 


A,C 


-L 






0113 


STA 


0121 


0116 


RST 


07 


0117 


NOP 




0118 


NOP 




0119 


STAX 


B 


011A 


NOP 




011B 


INR 


B 


011C 


INX 


B 


011D 


DCR 


B 


01 1E 


MVI 


B,01 


0120 


DCR 


B 


-XP 






P=0116 100 


Reset 



Review the code 
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— T Single step, and watch data values 

C0Z1M0E1I1 A=03 B=0003 D=0000 H=0121 S=0100 P=0100 MVI B,08*0102 
-T 

C0Z1M0E1I1 A=03 B=0803 D=0000 H=0121 S=0100 P=0102 MVI C,00*0104 
— T .count set 

( largest" set 

C0Z1M0E1I1 A=03 B=0800 D=0000 H=0121 S=0100 P=0104 LXI H,0119«0107 
-T 

f base address of data set 
C0Z1M0E1I1 A=03 B=0800 D=0000 H=0119 S=0100 P=0107 MOV A,M*0108 
-T 

f first data item brought to A 
C0Z1M0E1I1 A=02 B=0800 D=0000 H=0119 S=0100 P=0108 SUB C*0109 
-T 

C0Z0M0E0I1 A=02 B=0800 D=0000 H=0119 S=0100 P=0109 JC 010D*010C 
-T 

COZOMOEOM A=02 B=0800 D=0000 H=0119 S=0100 P=010C MOV C,A*010D 
-T 

f first data item moved to C correctly 
COZOMOEOM A=02 B=0802 D=0000 H=0119 S=0100 P=010D INX H>010E 
-T 

COZOMOEOM A=02 B=0802 D=0000 H=011A S=0100 P=010E DCR B'OIOF 
-T 

COZOMOEOM A=02 B=0702 D=0000 H=011A S=0100 P=010F JNZ 0107«0107 
-T 

COZOMOEOM A=02 B=0702 D=0000 H = 011A S=0100 P=0107 MOV A,M*0108 
-T 

second data item brought to A 
COZOMOEOM A=00 B=0702 D=0000 H=011A S=0100 P=0108 SUB C-0109 
-T 

f- subtract destroys data value which was loaded!!! 
C1Z0M1E0I0 A=FE B=0702 D=0000 H=011A S=0100 P=0109 JC 010D«010D 
-T 

C1Z0M1E0I0 A=FE B = 0702 D=0000 H=011A S=0100 P=010D INX H*010E 
- L100 

0100 MVI B,08 
0102 MVI COO 
0104 LXI H.0119 

0107 MOV A.M 

01 08 SUB C This should have been a CMP so that register A 

0109 JC 01 OD would not be destroyed 
01 OC MOV C.A 

010D INX H 
01 OE DCR B 
010F JNZ 0107 
0112 MOV A.C 
-A108 

0108 CMP C hot patch at 108H changes SUB to CMP 
0109 

— GO stop DDT for SAVE 
SAVE 1 SCAN.COM 

Save memory image 
A>DDT SCAN. COM Restart DDT 



16K DDT VER 1.0 
NEXT PC 
0200 0100 
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-XP 



P=0100 



-L116 



0116 RST 07 

0117 NOP 

0118 NOP } Look at code to see it it was properly loaded 

0119 STAX B ( (long typeout aborted with ruboutl 
011A NOP 

— (rubout) 

— G.1 16 Run from WOH to completion 
•0116 

— XC Look at Carry (accidental typol 
C1 

-X Look at CPU state 

C1Z1M0E1I1 A=06 B = 0006 D=OOO0 H=0121 S=0100 P=0116 RST 07 

— S121 Look at "Large" — it appears to be correct. 

0121 06 

0122 00 

0123 22 

-GO stop DDT 

ED SCAN. ASM Re-edit the source program, and make both changes 
•NSUB tl _ z 

*olt r 

SUB* C ; larger value in c? 
• ssubQcmp Qdlt 

cmp c ; larger value in c? 

jnc nfound ; jump if larger value not found 

' SNcQ fzXJLT 

JC NFOUND ;JUMP IF LARGER VALUE NOT FOUND 

*I 

ASM SCAN.AAZ Re-assemble, selecting source from disk A 

hex to disk A 

CP/M ASSEMBLER - VER 1 .0 print to Zfselects no print tile) 



0122 

002 H USE FACTOR 
END OF ASSEMBLY 



DDT SCAN. HEX Rerun debugger to check changes 



16K DDT VER 1.0 
NEXT PC 
0121 0000 
-L1 16 

0116 JMP 0000 check to ensure end is still at 11 6H 
0119 STAX B 
011 A NOP 
011B INR B 
— (ruboutl 
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— G100.116 Go from beginning with breakpoint at end 

EB OB 78 B1 .."!..' ,W X 

00 00 00 00 00 .... ) 

00 00 00 00 00 

— (rubout) aborts long typeout 

—GO stop DDT, debug session complete 



•0116 breakpoint reached 
-D121 Look at "LARGE" 

^ correct value computed 

0121 (56T00 22 21 00 02 7E EB 77 13 23 
0130 C2 27 01 C3 03 29 00 00 00 00 00 
0140 00 00 00 00 00 00 00 00 00 00 00 



168 CP/M Reference Manual 



Index 169 



Index 



A 

A (append) 98 
A (Assemble) 150 
ASM 

arithmetic operators 123 

assembler directives 126 

command 23 

DB 131 

DS 132 

DW 131 

END 127 

ENDIF 129 

EQU 127 

error messages 139 
file type 52 
IF 129 
labels 120 
logical operators 123 
numeric constants 121 
operation codes 132 
ORG 126 
overview 116 
program format 118 
reserved words 1 22 
sample session 140 
SET 128 

string constants 123 

B 

B (block mode transfer) 33 
BAK file type 52 



BAS file type 52 
BAT: 23 
BDOS 3 

BDOS error messages 43 
BIOS 3,46 

BIOS call conventions 50 
BOOT 49 
Built-in commands 

DIR 12 

ERA 11 

overview 10 

REN 13 

SAVE 14 

TYPE 14 

USER 15 

c 

Call conventions (BIOS) 46 
CCP (Console Command 

Processor) 4, 46 
Close file 64 
COM file 52 
Compute file size 76 
CON: 22 
Console input 57 
Console output 57 
Context editor 94 
Control characters 16 
CP/M 

built-in commands 10 
disk parameter block 5 
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CP/M (continued) 
file references 7 
file types 52 

general command structure 7 
line editing 15 
logical divisions 3 
transient commands 17 
Currently logged drive 10 

D 

D (delete) 33 
DB 131 

DDT (Dynamic Debugging Tool) 

A (Assemble) 150 

command list 149 

D (Display) 150 

R ( Fill) 151 

G (Go) 152 

I (Input) 153 

implementation 158 

L (List) 153 

M(Move) 154 

overview 149 

R(Read) 154 

S(Set) 155 

T (Trace) 156 

U(Untrace) 157 

X (Examine) 157 
Delete file 65 
DIR (directory) 12 
direct console I/O 58 
DS 132 
DUMP 43 
DW 131 

E 

E (echo) 33 
ED 

command strings 102 
command summary 110 
control characters 109 
errors 108 
memory buffer 99 
operation 95 



ED (continued) 

overview 95 

repetitive commands 107 

source libraries 107 

text alteration 103 

text editing 111 

text search 103 

text transfer 95 
END 127 
ENDIF 129 
EOF: 31 
EQU 127 
Error messages 

ASM 139 

BDOS 43 

ED 108 

F 

F (filter) 33 
FDOS 46, 50 
file control block 53 
file reference 7 
file types 52 

G 

G (get file) 34 

Get address (allocation) 70 

Get address (disk parameters) 72 

Get console status 61 

Get I/O Byte 59 

Get Read/Only vector 71 

Get user code 72 

General command structure 7 

H 

H (hex data transfer) 34 
Hex files 52 

/ 

I (ignore) 34 

IF 129 

INP: 31 

INT file type 52 

Intel 8080 2 
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J 

Jump codes 133 
L 

L (translate) 34 

Line editing commands 15 

List devices 23 

List output 58 

LOAD 26 

Logical devices 22 

LPT: 23 

LST: 23 

M 

Makefile 67 

Memory buffer organization 97 
Memory organization (CP/M) 47 

N 

N (add line numbers) 34 
NUL: 31 

o 

O (object file transfer) 34 
Open file 63 
Operand 120 
Operation codes 132 
ORG 126 
OUT: 31 

Output Control 15 
P 

P (include page ejects) 34 
PIP 27 

Physical devices 23 

Print string 59 

PRN: 31 

PTP: 23 

PTR: 23 

PUN: 23 

Punch output 58 



Q (quit copying) 34 



R 

R (read system files) 35 
RDR: 23 

Read console buffer 60 
Read random 73 
Read sequential 66 
Reader input 57 
REL file 52 
REN (REName) 13 
Reset disk system 62 
Return current disk 69 
Return login vector 68 
Return version number 61 

s 

S (start copying) 35 

Sample programs 
file dump utility 81 
file-to-file copy program 78 
random access program 84 

SAVE 14 

Search for First 64 

Search for Next 65 

Select disk 62 

SET 128 

Set DMA address 69 
Set file attributes 71 
Set I/O Byte 59 
Set random record 77 
Set user code 72 
Special characters 8 
STAT 1 8 
SUBMIT 40 
SYM file 52 

System function summary 92 
T 

T (expand tabs) 35 
Text transfer operations 95 
Transient commands 17 
TTY: 23 
TYPE 14 
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U 

U (all upper case) 35 

UC1: 23 

UL1: 23 

UP1: 23 

UP2: 23 

UR1: 23 

UR2: 23 

USER 15 

V 

V (verify) 35 
VAL 24 

w 

W (write over R/O) 35 
Write protect disk 70 
Write random 75 
Write sequential 66 

X 

XSUB 42 

z 

Z (zero parity bit on input) 35 
Zilog Z-80 2 



